tasklite-engine 3.0.0.dev0__tar.gz → 3.0.0.dev2__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 → tasklite_engine-3.0.0.dev2}/PKG-INFO +23 -16
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/README.md +22 -15
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/pyproject.toml +1 -1
- tasklite_engine-3.0.0.dev2/tasklite/__init__.py +77 -0
- tasklite_engine-3.0.0.dev2/tasklite/__main__.py +205 -0
- tasklite_engine-3.0.0.dev2/tasklite/_report.py +562 -0
- tasklite_engine-3.0.0.dev2/tasklite/backend/__init__.py +37 -0
- tasklite_engine-3.0.0.dev2/tasklite/backend/base.py +534 -0
- tasklite_engine-3.0.0.dev2/tasklite/backend/memory.py +611 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/backend/sqlite_backend.py +416 -488
- tasklite_engine-3.0.0.dev2/tasklite/edit.py +1276 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/engine/__init__.py +6 -7
- tasklite_engine-3.0.0.dev2/tasklite/engine/_worker_bootstrap.py +221 -0
- tasklite_engine-3.0.0.dev2/tasklite/engine/_worker_runtime.py +229 -0
- tasklite_engine-3.0.0.dev2/tasklite/engine/admission.py +147 -0
- tasklite_engine-3.0.0.dev2/tasklite/engine/authorization.py +989 -0
- tasklite_engine-3.0.0.dev2/tasklite/engine/channel.py +1084 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/engine/completion.py +193 -275
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/engine/config.py +5 -11
- tasklite_engine-3.0.0.dev2/tasklite/engine/dispatch.py +616 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/engine/governor.py +134 -69
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/engine/in_flight.py +20 -88
- tasklite_engine-3.0.0.dev2/tasklite/engine/launcher.py +1173 -0
- tasklite_engine-3.0.0.dev2/tasklite/engine/recovery.py +194 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/engine/resource.py +50 -103
- tasklite_engine-3.0.0.dev2/tasklite/engine/runtime.py +550 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/engine/scheduler.py +9 -46
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/engine/session.py +60 -15
- tasklite_engine-3.0.0.dev2/tasklite/engine/store.py +748 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/engine/types.py +29 -40
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/engine/wait.py +8 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/exceptions.py +0 -1
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/models/artifact.py +84 -62
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/models/context.py +37 -30
- tasklite_engine-3.0.0.dev2/tasklite/models/graph.py +114 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/models/job.py +3 -5
- tasklite_engine-3.0.0.dev2/tasklite/models/records.py +482 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/models/state.py +19 -125
- tasklite_engine-3.0.0.dev0/tasklite/triggers.py → tasklite_engine-3.0.0.dev2/tasklite/models/trigger.py +36 -5
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/pipeline.py +92 -100
- tasklite_engine-3.0.0.dev2/tasklite/resource.py +89 -0
- tasklite_engine-3.0.0.dev2/tasklite/snapshot.py +842 -0
- tasklite_engine-3.0.0.dev2/tasklite/testing.py +514 -0
- tasklite_engine-3.0.0.dev2/tasklite/utils/artifact.py +1183 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/utils/encoding.py +21 -40
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/utils/ipc.py +49 -1
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/utils/lockfile.py +50 -19
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/wrappers/__init__.py +1 -1
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/wrappers/discovery.py +13 -16
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/wrappers/http.py +77 -43
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite_engine.egg-info/PKG-INFO +23 -16
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite_engine.egg-info/SOURCES.txt +10 -20
- tasklite_engine-3.0.0.dev0/tasklite/__init__.py +0 -53
- tasklite_engine-3.0.0.dev0/tasklite/backend/__init__.py +0 -20
- tasklite_engine-3.0.0.dev0/tasklite/backend/base.py +0 -363
- tasklite_engine-3.0.0.dev0/tasklite/backend/memory.py +0 -689
- tasklite_engine-3.0.0.dev0/tasklite/contrib/__init__.py +0 -7
- tasklite_engine-3.0.0.dev0/tasklite/engine/admission.py +0 -241
- tasklite_engine-3.0.0.dev0/tasklite/engine/channel.py +0 -1021
- tasklite_engine-3.0.0.dev0/tasklite/engine/dispatch.py +0 -701
- tasklite_engine-3.0.0.dev0/tasklite/engine/execution_access.py +0 -39
- tasklite_engine-3.0.0.dev0/tasklite/engine/files.py +0 -52
- tasklite_engine-3.0.0.dev0/tasklite/engine/ops.py +0 -25
- tasklite_engine-3.0.0.dev0/tasklite/engine/recovery.py +0 -147
- tasklite_engine-3.0.0.dev0/tasklite/engine/runtime.py +0 -917
- tasklite_engine-3.0.0.dev0/tasklite/engine/selection.py +0 -186
- tasklite_engine-3.0.0.dev0/tasklite/engine/store.py +0 -975
- tasklite_engine-3.0.0.dev0/tasklite/hooks.py +0 -49
- tasklite_engine-3.0.0.dev0/tasklite/models/trigger.py +0 -18
- tasklite_engine-3.0.0.dev0/tasklite/resource.py +0 -12
- tasklite_engine-3.0.0.dev0/tasklite/snapshot.py +0 -639
- tasklite_engine-3.0.0.dev0/tasklite/testing.py +0 -101
- tasklite_engine-3.0.0.dev0/tasklite/utils/artifact.py +0 -271
- tasklite_engine-3.0.0.dev0/tests/test_encoding.py +0 -635
- tasklite_engine-3.0.0.dev0/tests/test_exception_contract.py +0 -155
- tasklite_engine-3.0.0.dev0/tests/test_exceptions.py +0 -86
- tasklite_engine-3.0.0.dev0/tests/test_hooks.py +0 -67
- tasklite_engine-3.0.0.dev0/tests/test_jsonutil.py +0 -97
- tasklite_engine-3.0.0.dev0/tests/test_package_surface.py +0 -389
- tasklite_engine-3.0.0.dev0/tests/test_packaging.py +0 -44
- tasklite_engine-3.0.0.dev0/tests/test_payload_intake.py +0 -81
- tasklite_engine-3.0.0.dev0/tests/test_pipeline.py +0 -1186
- tasklite_engine-3.0.0.dev0/tests/test_result_metadata.py +0 -87
- tasklite_engine-3.0.0.dev0/tests/test_testing.py +0 -217
- tasklite_engine-3.0.0.dev0/tests/test_trigger_contract.py +0 -316
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/LICENSE +0 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/setup.cfg +0 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/models/__init__.py +0 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/models/result.py +0 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/models/task.py +0 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/py.typed +0 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/selection.py +0 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/utils/__init__.py +0 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/utils/clock.py +0 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite/utils/jsonutil.py +0 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite_engine.egg-info/dependency_links.txt +0 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite_engine.egg-info/requires.txt +0 -0
- {tasklite_engine-3.0.0.dev0 → tasklite_engine-3.0.0.dev2}/tasklite_engine.egg-info/top_level.txt +0 -0
|
@@ -1,6 +1,6 @@
|
|
|
1
1
|
Metadata-Version: 2.4
|
|
2
2
|
Name: tasklite-engine
|
|
3
|
-
Version: 3.0.0.
|
|
3
|
+
Version: 3.0.0.dev2
|
|
4
4
|
Summary: A lightweight task orchestration engine with zero external dependencies, process isolation, and ACID persistence
|
|
5
5
|
License-Expression: MIT
|
|
6
6
|
Project-URL: Homepage, https://github.com/CaptainLi321/tasklite
|
|
@@ -39,7 +39,7 @@ Dynamic: license-file
|
|
|
39
39
|
[](LICENSE)
|
|
40
40
|
[](https://github.com/CaptainLi321/tasklite/actions/workflows/ci.yml)
|
|
41
41
|
|
|
42
|
-
当前开发版本为 **3.0.0.
|
|
42
|
+
当前开发版本为 **3.0.0.dev2**,公开接口与兼容性说明见 [API 参考手册](docs/API.md)。
|
|
43
43
|
|
|
44
44
|
---
|
|
45
45
|
|
|
@@ -79,7 +79,7 @@ flowchart TD
|
|
|
79
79
|
### 三层可靠性边界
|
|
80
80
|
1. **执行代标识与通道绑定 (Generation Fencing)**:每 worker 绑定独立单向 `Pipe` 与执行代标识,校验 `job_uid` 与 `execution_id`,旧执行与伪造消息无法污染状态机;
|
|
81
81
|
2. **已结算状态事务持久化**:IPC 仅负责本次运行的瞬时通信;已提交成功、失败与 `attempts` 由 SQLite 强事务持久化。异常退出遗留的 `running` 下次按失败收敛,`pending` 留队,不自动接续旧执行;
|
|
82
|
-
3. **单库级文件锁防护 (Library Lock Fencing)**:通过 `
|
|
82
|
+
3. **单库级文件锁防护 (Library Lock Fencing)**:通过 `<state_path>.lock`(如 `state.db.lock`)互斥保护,同一状态库同时只允许一个活动调度实例或管理写操作,避免并发写入破坏。
|
|
83
83
|
|
|
84
84
|
---
|
|
85
85
|
|
|
@@ -87,9 +87,9 @@ flowchart TD
|
|
|
87
87
|
|
|
88
88
|
### 1. 🛡️ 进程隔离与守护 (Process Isolation)
|
|
89
89
|
- 主进程作为总控调度器,不执行具体的业务代码;
|
|
90
|
-
-
|
|
91
|
-
-
|
|
92
|
-
-
|
|
90
|
+
- 每一个任务均在独立子进程中隔离执行(POSIX 独立进程组,Windows 无窗口独立控制台 + Job Object 绑定);
|
|
91
|
+
- 当子进程发生死循环或超时,看门狗将原子回收整棵子进程树(含多层孙进程)并自动释放资源;
|
|
92
|
+
- 支持 POSIX `SIGTERM`/`SIGINT` 与 Windows `SIGTERM`/`SIGINT`/`SIGBREAK` 优雅排空停机,子进程异常退出不影响主调度进程稳定运行。
|
|
93
93
|
|
|
94
94
|
### 2. ⚡ SQLite WAL 状态持久化 (ACID)
|
|
95
95
|
- 基于 SQLite WAL + `synchronous=FULL` 模式;
|
|
@@ -110,10 +110,11 @@ flowchart TD
|
|
|
110
110
|
|
|
111
111
|
### 6. 📦 统一文件声明与主进程清理授权
|
|
112
112
|
- `FileSpec` 明确文件角色(`output` / `input` / `cache`)与清理权限(`delete_existing` / `delete_on_failure` / `delete_on_success`);
|
|
113
|
-
-
|
|
113
|
+
- 主进程持有排他文件授权(含 Run 外 `grant_authorization` / `list_authorizations` / `revoke_authorization`)与跨平台(Linux / Windows)安全清理职责,收尾时先执行授权清理后提交事务。
|
|
114
114
|
|
|
115
|
-
### 7. 🎛️
|
|
116
|
-
-
|
|
115
|
+
### 7. 🎛️ 原子图修整、只读快照与运维 CLI
|
|
116
|
+
- Run 外通过 `pipeline.edit(dry_run=True)` 原子执行作业增、删、替换与状态流转,提交前全图闭环校验并支持 `tx.diff()` 预览;`attempts` 物理轨迹永不可删;
|
|
117
|
+
- 只读 `StateSnapshot.open(..., mode="lazy"|"copy")` 与 `StateSnapshot.report()` 提供零句柄运行前后对比与耗时/ETA 报告;并内置极简运维 CLI(`python -m tasklite status | set-status | remove`);
|
|
117
118
|
- `pipeline.run(exclude=Exclude(task_type="..."))` 支持按任务类型将作业安全留队至下次运行。
|
|
118
119
|
|
|
119
120
|
---
|
|
@@ -235,7 +236,7 @@ def agent_worker(job: Job, ctx) -> TaskResult:
|
|
|
235
236
|
return TaskResult.success(metadata={"tokens": result.get("usage", 0)})
|
|
236
237
|
|
|
237
238
|
pipeline = TaskLite(backend="sqlite", state_path="./agent_state.db", max_workers=8)
|
|
238
|
-
|
|
239
|
+
# 含清理标志的文件声明可通过交互授权或 TASKLITE_DANGEROUS_AUTO_APPROVE=1 确认
|
|
239
240
|
pipeline.register_resource(IntervalResource("llm_rpm", interval_seconds=0.1))
|
|
240
241
|
pipeline.register_task(Task("analyze", agent_worker, resources={"llm_rpm": 1.0}))
|
|
241
242
|
|
|
@@ -262,6 +263,7 @@ pipeline.close()
|
|
|
262
263
|
| **[`docs/adr/`](docs/adr/)** | **架构决策记录(ADR)**:关键架构演进、设计取舍与边界裁决依据 |
|
|
263
264
|
| **[`docs/ROADMAP.md`](docs/ROADMAP.md)** | **未来演进路线图**:已分析但尚未立项实施的储备方向(实施前须立项 ADR) |
|
|
264
265
|
| **[`AGENTS.md`](AGENTS.md)** | **研发红线与工作流规范**:测试门槛、原子提交纪律、分层依赖红线与注释规范 |
|
|
266
|
+
| **[`examples/edit_migrations/`](examples/edit_migrations/)** | **原子图迁移参考脚本**:换盘搬迁、历史缓存纳管、分支改名、调大超时重跑、中间插层 5 个可运行模板 |
|
|
265
267
|
| **[`CHANGELOG.md`](CHANGELOG.md)** | **版本变更日志**:各发布版本的显著特性与破坏性变更记录 |
|
|
266
268
|
|
|
267
269
|
---
|
|
@@ -271,11 +273,14 @@ pipeline.close()
|
|
|
271
273
|
```
|
|
272
274
|
tasklite/
|
|
273
275
|
├── pipeline.py # TaskLite 核心门面与装配
|
|
276
|
+
├── edit.py # EditTransaction:Run 外原子图修整事务与闭环校验
|
|
277
|
+
├── snapshot.py # StateSnapshot:只读一致状态快照、copy 模式与 JSON 查询
|
|
278
|
+
├── _report.py # StateSnapshot.report 状态/耗时/ETA 与前后对比渲染
|
|
279
|
+
├── __main__.py # 极简运维 CLI(python -m tasklite status / set-status / remove)
|
|
274
280
|
├── selection.py # 执行选择规则值对象 Exclude(候选准入 seam)
|
|
275
281
|
├── resource.py # 内置资源公共导出门面 (CapacityResource, IntervalResource)
|
|
276
|
-
├── snapshot.py # StateSnapshot:只读一致状态快照与标准 JSON 查询
|
|
277
282
|
├── exceptions.py # 异常族 (TaskLiteError)
|
|
278
|
-
├── testing.py # fake_ctx
|
|
283
|
+
├── testing.py # 测试辅助工具(fake_ctx / running / authorizer / in_process_workers 等)
|
|
279
284
|
├── engine/ # 核心调度与执行引擎群
|
|
280
285
|
│ ├── runtime.py # 核心运行期深模块、主循环事件泵 (EngineRuntime)
|
|
281
286
|
│ ├── config.py # RunConfig 静态装配快照、默认值唯一解析点
|
|
@@ -283,11 +288,14 @@ tasklite/
|
|
|
283
288
|
│ ├── wait.py # 事件泵等待/空闲决策纯函数
|
|
284
289
|
│ ├── types.py # 引擎公共值对象单一真相源
|
|
285
290
|
│ ├── store.py # 状态事务与失败写入隔离 (StateStore)
|
|
286
|
-
│ ├── ops.py # OpsConsole:run() 外纯运维接缝(管理 API 委托目标)
|
|
287
291
|
│ ├── dispatch.py # 任务派发状态机 (DispatchMachine)
|
|
288
292
|
│ ├── completion.py # 任务完成与提交单一收口 (CompletionMachine)
|
|
293
|
+
│ ├── authorization.py # 主进程文件声明与三类授权等待协调器 (AuthorizationCoordinator)
|
|
289
294
|
│ ├── recovery.py # 遗留 running 收敛与在途中止编排 (RecoveryOrchestrator)
|
|
290
295
|
│ ├── channel.py # IPC 与子进程执行通道 (ExecutionChannel)
|
|
296
|
+
│ ├── launcher.py # 跨平台 Worker 启动器与进程树原子回收 (WorkerLauncher / ProcessTreeAdapter)
|
|
297
|
+
│ ├── _worker_runtime.py # 纯 Worker 侧执行入口、启动规格与跨平台停止信号单一事实源
|
|
298
|
+
│ ├── _worker_bootstrap.py # Worker 子进程独立引导与握手屏障
|
|
291
299
|
│ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler / OrderingPolicy 排序 seam)
|
|
292
300
|
│ ├── admission.py # 重入队节奏 (RequeuePolicy seam)
|
|
293
301
|
│ ├── governor.py # 死锁归因仲裁与依赖宽限 (DeadlockGovernor)
|
|
@@ -295,9 +303,8 @@ tasklite/
|
|
|
295
303
|
│ └── resource.py # 内置资源实现
|
|
296
304
|
├── backend/ # SQLite WAL 强一致事务持久化后端与内存后端
|
|
297
305
|
├── models/ # Task / Job / Attempt / JobContext / TaskResult / FileSpec 数据模型
|
|
298
|
-
├── wrappers/ # 可选工具:discovery.py(增量扫描)/ http.py
|
|
299
|
-
|
|
300
|
-
└── utils/ # 单射编码 (%XX 转义) / 瞬时 Pipe 通道 / 文件锁 / 时钟 / JSON 校验
|
|
306
|
+
├── wrappers/ # 可选工具:discovery.py(增量扫描)/ http.py(HTTP 请求、重试与快照)
|
|
307
|
+
└── utils/ # 单射编码 (%XX 转义) / 瞬时 Pipe 通道 / 跨平台路径策略 / 文件锁 / 时钟 / JSON 校验
|
|
301
308
|
```
|
|
302
309
|
|
|
303
310
|
---
|
|
@@ -8,7 +8,7 @@
|
|
|
8
8
|
[](LICENSE)
|
|
9
9
|
[](https://github.com/CaptainLi321/tasklite/actions/workflows/ci.yml)
|
|
10
10
|
|
|
11
|
-
当前开发版本为 **3.0.0.
|
|
11
|
+
当前开发版本为 **3.0.0.dev2**,公开接口与兼容性说明见 [API 参考手册](docs/API.md)。
|
|
12
12
|
|
|
13
13
|
---
|
|
14
14
|
|
|
@@ -48,7 +48,7 @@ flowchart TD
|
|
|
48
48
|
### 三层可靠性边界
|
|
49
49
|
1. **执行代标识与通道绑定 (Generation Fencing)**:每 worker 绑定独立单向 `Pipe` 与执行代标识,校验 `job_uid` 与 `execution_id`,旧执行与伪造消息无法污染状态机;
|
|
50
50
|
2. **已结算状态事务持久化**:IPC 仅负责本次运行的瞬时通信;已提交成功、失败与 `attempts` 由 SQLite 强事务持久化。异常退出遗留的 `running` 下次按失败收敛,`pending` 留队,不自动接续旧执行;
|
|
51
|
-
3. **单库级文件锁防护 (Library Lock Fencing)**:通过 `
|
|
51
|
+
3. **单库级文件锁防护 (Library Lock Fencing)**:通过 `<state_path>.lock`(如 `state.db.lock`)互斥保护,同一状态库同时只允许一个活动调度实例或管理写操作,避免并发写入破坏。
|
|
52
52
|
|
|
53
53
|
---
|
|
54
54
|
|
|
@@ -56,9 +56,9 @@ flowchart TD
|
|
|
56
56
|
|
|
57
57
|
### 1. 🛡️ 进程隔离与守护 (Process Isolation)
|
|
58
58
|
- 主进程作为总控调度器,不执行具体的业务代码;
|
|
59
|
-
-
|
|
60
|
-
-
|
|
61
|
-
-
|
|
59
|
+
- 每一个任务均在独立子进程中隔离执行(POSIX 独立进程组,Windows 无窗口独立控制台 + Job Object 绑定);
|
|
60
|
+
- 当子进程发生死循环或超时,看门狗将原子回收整棵子进程树(含多层孙进程)并自动释放资源;
|
|
61
|
+
- 支持 POSIX `SIGTERM`/`SIGINT` 与 Windows `SIGTERM`/`SIGINT`/`SIGBREAK` 优雅排空停机,子进程异常退出不影响主调度进程稳定运行。
|
|
62
62
|
|
|
63
63
|
### 2. ⚡ SQLite WAL 状态持久化 (ACID)
|
|
64
64
|
- 基于 SQLite WAL + `synchronous=FULL` 模式;
|
|
@@ -79,10 +79,11 @@ flowchart TD
|
|
|
79
79
|
|
|
80
80
|
### 6. 📦 统一文件声明与主进程清理授权
|
|
81
81
|
- `FileSpec` 明确文件角色(`output` / `input` / `cache`)与清理权限(`delete_existing` / `delete_on_failure` / `delete_on_success`);
|
|
82
|
-
-
|
|
82
|
+
- 主进程持有排他文件授权(含 Run 外 `grant_authorization` / `list_authorizations` / `revoke_authorization`)与跨平台(Linux / Windows)安全清理职责,收尾时先执行授权清理后提交事务。
|
|
83
83
|
|
|
84
|
-
### 7. 🎛️
|
|
85
|
-
-
|
|
84
|
+
### 7. 🎛️ 原子图修整、只读快照与运维 CLI
|
|
85
|
+
- Run 外通过 `pipeline.edit(dry_run=True)` 原子执行作业增、删、替换与状态流转,提交前全图闭环校验并支持 `tx.diff()` 预览;`attempts` 物理轨迹永不可删;
|
|
86
|
+
- 只读 `StateSnapshot.open(..., mode="lazy"|"copy")` 与 `StateSnapshot.report()` 提供零句柄运行前后对比与耗时/ETA 报告;并内置极简运维 CLI(`python -m tasklite status | set-status | remove`);
|
|
86
87
|
- `pipeline.run(exclude=Exclude(task_type="..."))` 支持按任务类型将作业安全留队至下次运行。
|
|
87
88
|
|
|
88
89
|
---
|
|
@@ -204,7 +205,7 @@ def agent_worker(job: Job, ctx) -> TaskResult:
|
|
|
204
205
|
return TaskResult.success(metadata={"tokens": result.get("usage", 0)})
|
|
205
206
|
|
|
206
207
|
pipeline = TaskLite(backend="sqlite", state_path="./agent_state.db", max_workers=8)
|
|
207
|
-
|
|
208
|
+
# 含清理标志的文件声明可通过交互授权或 TASKLITE_DANGEROUS_AUTO_APPROVE=1 确认
|
|
208
209
|
pipeline.register_resource(IntervalResource("llm_rpm", interval_seconds=0.1))
|
|
209
210
|
pipeline.register_task(Task("analyze", agent_worker, resources={"llm_rpm": 1.0}))
|
|
210
211
|
|
|
@@ -231,6 +232,7 @@ pipeline.close()
|
|
|
231
232
|
| **[`docs/adr/`](docs/adr/)** | **架构决策记录(ADR)**:关键架构演进、设计取舍与边界裁决依据 |
|
|
232
233
|
| **[`docs/ROADMAP.md`](docs/ROADMAP.md)** | **未来演进路线图**:已分析但尚未立项实施的储备方向(实施前须立项 ADR) |
|
|
233
234
|
| **[`AGENTS.md`](AGENTS.md)** | **研发红线与工作流规范**:测试门槛、原子提交纪律、分层依赖红线与注释规范 |
|
|
235
|
+
| **[`examples/edit_migrations/`](examples/edit_migrations/)** | **原子图迁移参考脚本**:换盘搬迁、历史缓存纳管、分支改名、调大超时重跑、中间插层 5 个可运行模板 |
|
|
234
236
|
| **[`CHANGELOG.md`](CHANGELOG.md)** | **版本变更日志**:各发布版本的显著特性与破坏性变更记录 |
|
|
235
237
|
|
|
236
238
|
---
|
|
@@ -240,11 +242,14 @@ pipeline.close()
|
|
|
240
242
|
```
|
|
241
243
|
tasklite/
|
|
242
244
|
├── pipeline.py # TaskLite 核心门面与装配
|
|
245
|
+
├── edit.py # EditTransaction:Run 外原子图修整事务与闭环校验
|
|
246
|
+
├── snapshot.py # StateSnapshot:只读一致状态快照、copy 模式与 JSON 查询
|
|
247
|
+
├── _report.py # StateSnapshot.report 状态/耗时/ETA 与前后对比渲染
|
|
248
|
+
├── __main__.py # 极简运维 CLI(python -m tasklite status / set-status / remove)
|
|
243
249
|
├── selection.py # 执行选择规则值对象 Exclude(候选准入 seam)
|
|
244
250
|
├── resource.py # 内置资源公共导出门面 (CapacityResource, IntervalResource)
|
|
245
|
-
├── snapshot.py # StateSnapshot:只读一致状态快照与标准 JSON 查询
|
|
246
251
|
├── exceptions.py # 异常族 (TaskLiteError)
|
|
247
|
-
├── testing.py # fake_ctx
|
|
252
|
+
├── testing.py # 测试辅助工具(fake_ctx / running / authorizer / in_process_workers 等)
|
|
248
253
|
├── engine/ # 核心调度与执行引擎群
|
|
249
254
|
│ ├── runtime.py # 核心运行期深模块、主循环事件泵 (EngineRuntime)
|
|
250
255
|
│ ├── config.py # RunConfig 静态装配快照、默认值唯一解析点
|
|
@@ -252,11 +257,14 @@ tasklite/
|
|
|
252
257
|
│ ├── wait.py # 事件泵等待/空闲决策纯函数
|
|
253
258
|
│ ├── types.py # 引擎公共值对象单一真相源
|
|
254
259
|
│ ├── store.py # 状态事务与失败写入隔离 (StateStore)
|
|
255
|
-
│ ├── ops.py # OpsConsole:run() 外纯运维接缝(管理 API 委托目标)
|
|
256
260
|
│ ├── dispatch.py # 任务派发状态机 (DispatchMachine)
|
|
257
261
|
│ ├── completion.py # 任务完成与提交单一收口 (CompletionMachine)
|
|
262
|
+
│ ├── authorization.py # 主进程文件声明与三类授权等待协调器 (AuthorizationCoordinator)
|
|
258
263
|
│ ├── recovery.py # 遗留 running 收敛与在途中止编排 (RecoveryOrchestrator)
|
|
259
264
|
│ ├── channel.py # IPC 与子进程执行通道 (ExecutionChannel)
|
|
265
|
+
│ ├── launcher.py # 跨平台 Worker 启动器与进程树原子回收 (WorkerLauncher / ProcessTreeAdapter)
|
|
266
|
+
│ ├── _worker_runtime.py # 纯 Worker 侧执行入口、启动规格与跨平台停止信号单一事实源
|
|
267
|
+
│ ├── _worker_bootstrap.py # Worker 子进程独立引导与握手屏障
|
|
260
268
|
│ ├── scheduler.py # 资源调度与 DAG 依赖 (JobScheduler / OrderingPolicy 排序 seam)
|
|
261
269
|
│ ├── admission.py # 重入队节奏 (RequeuePolicy seam)
|
|
262
270
|
│ ├── governor.py # 死锁归因仲裁与依赖宽限 (DeadlockGovernor)
|
|
@@ -264,9 +272,8 @@ tasklite/
|
|
|
264
272
|
│ └── resource.py # 内置资源实现
|
|
265
273
|
├── backend/ # SQLite WAL 强一致事务持久化后端与内存后端
|
|
266
274
|
├── models/ # Task / Job / Attempt / JobContext / TaskResult / FileSpec 数据模型
|
|
267
|
-
├── wrappers/ # 可选工具:discovery.py(增量扫描)/ http.py
|
|
268
|
-
|
|
269
|
-
└── utils/ # 单射编码 (%XX 转义) / 瞬时 Pipe 通道 / 文件锁 / 时钟 / JSON 校验
|
|
275
|
+
├── wrappers/ # 可选工具:discovery.py(增量扫描)/ http.py(HTTP 请求、重试与快照)
|
|
276
|
+
└── utils/ # 单射编码 (%XX 转义) / 瞬时 Pipe 通道 / 跨平台路径策略 / 文件锁 / 时钟 / JSON 校验
|
|
270
277
|
```
|
|
271
278
|
|
|
272
279
|
---
|
|
@@ -0,0 +1,77 @@
|
|
|
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/wrappers/``。
|
|
18
|
+
"""
|
|
19
|
+
from __future__ import annotations
|
|
20
|
+
|
|
21
|
+
import importlib
|
|
22
|
+
from typing import TYPE_CHECKING, Any
|
|
23
|
+
|
|
24
|
+
__version__ = "3.0.0.dev2"
|
|
25
|
+
|
|
26
|
+
if TYPE_CHECKING:
|
|
27
|
+
from .exceptions import TaskLiteError
|
|
28
|
+
from .models.artifact import FileSpec
|
|
29
|
+
from .models.context import JobContext
|
|
30
|
+
from .models.job import Job
|
|
31
|
+
from .models.result import TaskResult
|
|
32
|
+
from .models.task import Task
|
|
33
|
+
from .pipeline import TaskLite
|
|
34
|
+
from .snapshot import StateSnapshot
|
|
35
|
+
from .utils.encoding import make_job_uid, parse_job_uid
|
|
36
|
+
|
|
37
|
+
# 根包延迟导出表(PEP 562):避免子进程引导导入 ``tasklite.engine._worker_bootstrap``
|
|
38
|
+
# 时连带拉起父进程门面、快照与持久化树。
|
|
39
|
+
_LAZY_EXPORTS: dict[str, tuple[str, str]] = {
|
|
40
|
+
"TaskLite": (".pipeline", "TaskLite"),
|
|
41
|
+
"Task": (".models.task", "Task"),
|
|
42
|
+
"Job": (".models.job", "Job"),
|
|
43
|
+
"JobContext": (".models.context", "JobContext"),
|
|
44
|
+
"TaskResult": (".models.result", "TaskResult"),
|
|
45
|
+
"FileSpec": (".models.artifact", "FileSpec"),
|
|
46
|
+
"StateSnapshot": (".snapshot", "StateSnapshot"),
|
|
47
|
+
"TaskLiteError": (".exceptions", "TaskLiteError"),
|
|
48
|
+
"make_job_uid": (".utils.encoding", "make_job_uid"),
|
|
49
|
+
"parse_job_uid": (".utils.encoding", "parse_job_uid"),
|
|
50
|
+
}
|
|
51
|
+
|
|
52
|
+
__all__ = [
|
|
53
|
+
"TaskLite",
|
|
54
|
+
"Task",
|
|
55
|
+
"Job",
|
|
56
|
+
"JobContext",
|
|
57
|
+
"TaskResult",
|
|
58
|
+
"FileSpec",
|
|
59
|
+
"StateSnapshot",
|
|
60
|
+
"TaskLiteError",
|
|
61
|
+
"make_job_uid",
|
|
62
|
+
"parse_job_uid",
|
|
63
|
+
]
|
|
64
|
+
|
|
65
|
+
|
|
66
|
+
def __getattr__(name: str) -> Any:
|
|
67
|
+
target = _LAZY_EXPORTS.get(name)
|
|
68
|
+
if target is None:
|
|
69
|
+
raise AttributeError(f"module {__name__!r} has no attribute {name!r}")
|
|
70
|
+
module_name, attr_name = target
|
|
71
|
+
value = getattr(importlib.import_module(module_name, __name__), attr_name)
|
|
72
|
+
globals()[name] = value
|
|
73
|
+
return value
|
|
74
|
+
|
|
75
|
+
|
|
76
|
+
def __dir__() -> list[str]:
|
|
77
|
+
return sorted(set(globals()) | set(__all__))
|
|
@@ -0,0 +1,205 @@
|
|
|
1
|
+
"""TaskLite 极简运维命令行入口(``python -m tasklite``,ADR-0012 §3.4)。
|
|
2
|
+
|
|
3
|
+
严格定位于只读观测与纯 ``uid`` 驱动的轻量状态运维:
|
|
4
|
+
- ``status``:薄封装 ``StateSnapshot.open`` 与 ``StateSnapshot.report``;
|
|
5
|
+
- ``set-status`` / ``remove``:100% 委托 ``TaskLite.edit()``,默认预览不落盘,
|
|
6
|
+
显式传入 ``--apply`` 才原子提交;
|
|
7
|
+
- 所有子命令强制要求显式传入 ``<state_path>``,修改类命令前置校验路径存在且非目录,
|
|
8
|
+
绝不静默新建空数据库文件。
|
|
9
|
+
"""
|
|
10
|
+
from __future__ import annotations
|
|
11
|
+
|
|
12
|
+
import argparse
|
|
13
|
+
from collections.abc import Sequence
|
|
14
|
+
from pathlib import Path
|
|
15
|
+
import sqlite3
|
|
16
|
+
import sys
|
|
17
|
+
from typing import Literal, TextIO, cast
|
|
18
|
+
|
|
19
|
+
from .backend.sqlite_backend import verify_existing_sqlite_database
|
|
20
|
+
from .exceptions import TaskLiteError
|
|
21
|
+
from .pipeline import TaskLite
|
|
22
|
+
from .snapshot import StateSnapshot
|
|
23
|
+
|
|
24
|
+
|
|
25
|
+
def _safe_print(text: str, *, file: TextIO) -> None:
|
|
26
|
+
"""在窄编码终端管道(如 Windows GBK)下安全输出文本,避免渲染符号触发编码异常。"""
|
|
27
|
+
try:
|
|
28
|
+
print(text, file=file)
|
|
29
|
+
except UnicodeEncodeError:
|
|
30
|
+
encoding = getattr(file, "encoding", None) or "utf-8"
|
|
31
|
+
safe_text = text.encode(encoding, errors="replace").decode(encoding)
|
|
32
|
+
print(safe_text, file=file)
|
|
33
|
+
|
|
34
|
+
|
|
35
|
+
def _validate_existing_state_path(raw_path: str) -> Path:
|
|
36
|
+
"""修改类子命令前置校验:只读探活已存在的 Schema 6 状态库,杜绝静默建空库或写入 WAL/SHM。"""
|
|
37
|
+
if not raw_path or not raw_path.strip():
|
|
38
|
+
raise TaskLiteError("state_path must be a non-empty file path")
|
|
39
|
+
return verify_existing_sqlite_database(raw_path)
|
|
40
|
+
|
|
41
|
+
|
|
42
|
+
def _parse_entries(raw_entries: str) -> list[Literal["queue", "successes", "failures"]]:
|
|
43
|
+
"""按逗号拆分并去除空白;空值或非法分区名保留交由 EditTransaction.remove 统一校验。"""
|
|
44
|
+
if not raw_entries.strip():
|
|
45
|
+
return []
|
|
46
|
+
parts = [part.strip() for part in raw_entries.split(",")]
|
|
47
|
+
return cast(list[Literal["queue", "successes", "failures"]], parts)
|
|
48
|
+
|
|
49
|
+
|
|
50
|
+
def _add_recursive_group(subparser: argparse.ArgumentParser) -> None:
|
|
51
|
+
"""要求显式二选一传入 --recursive 或 --no-recursive。"""
|
|
52
|
+
group = subparser.add_mutually_exclusive_group(required=True)
|
|
53
|
+
group.add_argument(
|
|
54
|
+
"--recursive",
|
|
55
|
+
dest="recursive",
|
|
56
|
+
action="store_true",
|
|
57
|
+
help="沿正向 depends_on 闭包级联作用于全部下游作业",
|
|
58
|
+
)
|
|
59
|
+
group.add_argument(
|
|
60
|
+
"--no-recursive",
|
|
61
|
+
dest="recursive",
|
|
62
|
+
action="store_false",
|
|
63
|
+
help="仅作用于指定的单个作业,不级联下游",
|
|
64
|
+
)
|
|
65
|
+
|
|
66
|
+
|
|
67
|
+
def _build_parser() -> argparse.ArgumentParser:
|
|
68
|
+
parser = argparse.ArgumentParser(
|
|
69
|
+
prog="python -m tasklite",
|
|
70
|
+
description="TaskLite 运维命令行工具(只读观测与纯 UID 级状态修整)。",
|
|
71
|
+
)
|
|
72
|
+
subparsers = parser.add_subparsers(dest="command", required=True)
|
|
73
|
+
|
|
74
|
+
# 1. status
|
|
75
|
+
status_parser = subparsers.add_parser(
|
|
76
|
+
"status",
|
|
77
|
+
help="输出状态库只读状态与耗时报告",
|
|
78
|
+
)
|
|
79
|
+
status_parser.add_argument(
|
|
80
|
+
"state_path",
|
|
81
|
+
help="SQLite 状态库文件路径(必填)",
|
|
82
|
+
)
|
|
83
|
+
|
|
84
|
+
# 2. set-status
|
|
85
|
+
set_status_parser = subparsers.add_parser(
|
|
86
|
+
"set-status",
|
|
87
|
+
help="将指定作业(可选级联下游)流转为 pending 或 failed",
|
|
88
|
+
)
|
|
89
|
+
set_status_parser.add_argument(
|
|
90
|
+
"state_path",
|
|
91
|
+
help="SQLite 状态库文件路径(必填)",
|
|
92
|
+
)
|
|
93
|
+
set_status_parser.add_argument(
|
|
94
|
+
"uid",
|
|
95
|
+
help="目标作业规范 UID(task_type::job_id)",
|
|
96
|
+
)
|
|
97
|
+
set_status_parser.add_argument(
|
|
98
|
+
"status",
|
|
99
|
+
choices=("pending", "failed"),
|
|
100
|
+
help="目标状态(仅允许 pending 或 failed)",
|
|
101
|
+
)
|
|
102
|
+
_add_recursive_group(set_status_parser)
|
|
103
|
+
set_status_parser.add_argument(
|
|
104
|
+
"--note",
|
|
105
|
+
default=None,
|
|
106
|
+
help="可选运维备注,写入事务变更记录",
|
|
107
|
+
)
|
|
108
|
+
set_status_parser.add_argument(
|
|
109
|
+
"--apply",
|
|
110
|
+
action="store_true",
|
|
111
|
+
default=False,
|
|
112
|
+
help="显式提交落盘(默认仅 dry-run 预览不写入数据库)",
|
|
113
|
+
)
|
|
114
|
+
|
|
115
|
+
# 3. remove
|
|
116
|
+
remove_parser = subparsers.add_parser(
|
|
117
|
+
"remove",
|
|
118
|
+
help="从指定分区移除作业条目(永不删除 attempts 或磁盘文件)",
|
|
119
|
+
)
|
|
120
|
+
remove_parser.add_argument(
|
|
121
|
+
"state_path",
|
|
122
|
+
help="SQLite 状态库文件路径(必填)",
|
|
123
|
+
)
|
|
124
|
+
remove_parser.add_argument(
|
|
125
|
+
"uid",
|
|
126
|
+
help="目标作业规范 UID(task_type::job_id)",
|
|
127
|
+
)
|
|
128
|
+
remove_parser.add_argument(
|
|
129
|
+
"--entries",
|
|
130
|
+
default="queue,successes,failures",
|
|
131
|
+
help="逗号分隔的目标分区列表(默认: queue,successes,failures)",
|
|
132
|
+
)
|
|
133
|
+
_add_recursive_group(remove_parser)
|
|
134
|
+
remove_parser.add_argument(
|
|
135
|
+
"--note",
|
|
136
|
+
default=None,
|
|
137
|
+
help="可选运维备注",
|
|
138
|
+
)
|
|
139
|
+
remove_parser.add_argument(
|
|
140
|
+
"--apply",
|
|
141
|
+
action="store_true",
|
|
142
|
+
default=False,
|
|
143
|
+
help="显式提交落盘(默认仅 dry-run 预览不写入数据库)",
|
|
144
|
+
)
|
|
145
|
+
|
|
146
|
+
return parser
|
|
147
|
+
|
|
148
|
+
|
|
149
|
+
def _cmd_status(args: argparse.Namespace) -> int:
|
|
150
|
+
with StateSnapshot.open(args.state_path) as snap:
|
|
151
|
+
_safe_print(StateSnapshot.report(snap), file=sys.stdout)
|
|
152
|
+
return 0
|
|
153
|
+
|
|
154
|
+
|
|
155
|
+
def _cmd_set_status(args: argparse.Namespace) -> int:
|
|
156
|
+
db_path = _validate_existing_state_path(args.state_path)
|
|
157
|
+
target_status: Literal["pending", "failed"] = (
|
|
158
|
+
"pending" if args.status == "pending" else "failed"
|
|
159
|
+
)
|
|
160
|
+
with TaskLite(backend="sqlite", state_path=db_path) as pipeline:
|
|
161
|
+
with pipeline.edit(dry_run=not args.apply, note=args.note) as tx:
|
|
162
|
+
tx.set_status(args.uid, target_status, recursive=bool(args.recursive))
|
|
163
|
+
_safe_print(tx.diff(), file=sys.stdout)
|
|
164
|
+
if not args.apply:
|
|
165
|
+
_safe_print(
|
|
166
|
+
"Dry-run preview only; no changes written. Re-run with --apply to commit.",
|
|
167
|
+
file=sys.stdout,
|
|
168
|
+
)
|
|
169
|
+
return 0
|
|
170
|
+
|
|
171
|
+
|
|
172
|
+
def _cmd_remove(args: argparse.Namespace) -> int:
|
|
173
|
+
db_path = _validate_existing_state_path(args.state_path)
|
|
174
|
+
entries = _parse_entries(args.entries)
|
|
175
|
+
with TaskLite(backend="sqlite", state_path=db_path) as pipeline:
|
|
176
|
+
with pipeline.edit(dry_run=not args.apply, note=args.note) as tx:
|
|
177
|
+
tx.remove(args.uid, entries=entries, recursive=bool(args.recursive))
|
|
178
|
+
_safe_print(tx.diff(), file=sys.stdout)
|
|
179
|
+
if not args.apply:
|
|
180
|
+
_safe_print(
|
|
181
|
+
"Dry-run preview only; no changes written. Re-run with --apply to commit.",
|
|
182
|
+
file=sys.stdout,
|
|
183
|
+
)
|
|
184
|
+
return 0
|
|
185
|
+
|
|
186
|
+
|
|
187
|
+
def main(argv: Sequence[str] | None = None) -> int:
|
|
188
|
+
"""CLI 主入口,返回标准进程退出码(0 成功,1 运行/校验失败,2 参数错误)。"""
|
|
189
|
+
parser = _build_parser()
|
|
190
|
+
args = parser.parse_args(argv)
|
|
191
|
+
try:
|
|
192
|
+
if args.command == "status":
|
|
193
|
+
return _cmd_status(args)
|
|
194
|
+
if args.command == "set-status":
|
|
195
|
+
return _cmd_set_status(args)
|
|
196
|
+
if args.command == "remove":
|
|
197
|
+
return _cmd_remove(args)
|
|
198
|
+
raise TaskLiteError(f"Unknown command: {args.command!r}")
|
|
199
|
+
except (TaskLiteError, OSError, sqlite3.Error) as exc:
|
|
200
|
+
_safe_print(f"Error: {exc}", file=sys.stderr)
|
|
201
|
+
return 1
|
|
202
|
+
|
|
203
|
+
|
|
204
|
+
if __name__ == "__main__":
|
|
205
|
+
raise SystemExit(main())
|