@faapi/faapi 6.32.0 → 6.34.0

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.
@@ -196,6 +196,8 @@ interface TaskDriverJob {
196
196
  attempt: number;
197
197
  /** 停机/取消信号;驱动不支持取消时为永不 abort 的信号 */
198
198
  signal: AbortSignal;
199
+ /** 所属任务组(组投递的成员任务携带;驱动在交付时从组标识载体还原) */
200
+ groupId?: string;
199
201
  }
200
202
  /** 语义层交给驱动层的执行函数(抛错 = 失败,由驱动按入队时的 retries 重试) */
201
203
  type TaskDriverProcess = (job: TaskDriverJob) => Promise<unknown>;
@@ -217,6 +219,8 @@ interface TaskDriverRecord {
217
219
  result?: unknown;
218
220
  /** 失败/取消原因 */
219
221
  error?: string;
222
+ /** 所属任务组(组投递的成员任务携带;驱动从组标识载体还原后返回) */
223
+ groupId?: string;
220
224
  createdAt: number;
221
225
  /** 计划执行时间戳(延迟任务) */
222
226
  runAt?: number;
@@ -244,6 +248,12 @@ interface TaskDriver {
244
248
  dedupId?: string;
245
249
  timeoutMs?: number;
246
250
  graceMs?: number;
251
+ /**
252
+ * 所属任务组(组投递成员携带,可选)——驱动以此把组标识随任务持久化
253
+ * (载体为驱动内部实现,两内置驱动以载荷包装形态存储),交付/查询时还原为
254
+ * `TaskDriverJob.groupId` / `TaskDriverRecord.groupId`
255
+ */
256
+ groupId?: string;
247
257
  }): Promise<string>;
248
258
  /**
249
259
  * 注册某任务的消费 worker(幂等覆盖)。process 抛错 = 本次失败,驱动决定重试。
@@ -282,6 +292,60 @@ interface TaskDriver {
282
292
  * 任务不存在 / 状态不允许时由驱动抛错。
283
293
  */
284
294
  retry?(name: string, id: string): Promise<void>;
295
+ /**
296
+ * 任务组记账(可选能力,整对象实现——未实现时 TaskClient.enqueueGroup /
297
+ * getGroup 显式抛错)。语义与两内置驱动的存储映射见 taskGroups.md。
298
+ *
299
+ * 记账语义约束(实现须满足):
300
+ * - 成员落定**幂等**——同一成员重复 settle 不重复计数(成员行 settled 守卫)
301
+ * - settle/unsettle 的计数与成员状态翻转须原子(单条 SQL / Lua)
302
+ * - 记账状态持久化在驱动存储,跨实例/重启正确
303
+ */
304
+ groups?: TaskDriverGroupOps;
305
+ }
306
+ /** 组记账 create 的声明(enqueueGroup 语义层透传) */
307
+ interface TaskDriverGroupCreate {
308
+ id: string;
309
+ /** 成员任务名(一组一个任务名) */
310
+ task: string;
311
+ total: number;
312
+ onComplete?: string;
313
+ onFailure: TaskGroupOnFailure;
314
+ }
315
+ /** settle 的返回:记账后快照 + 是否本次落定使组到达全部落定 */
316
+ type TaskDriverGroupSettleResult = TaskGroupSnapshot & {
317
+ /** 本次落定后 settled >= total */
318
+ isLast: boolean;
319
+ };
320
+ /**
321
+ * 任务组记账驱动能力(TaskDriver.groups)
322
+ */
323
+ interface TaskDriverGroupOps {
324
+ /**
325
+ * 创建组记账。同 id 重复创建:参数完全一致幂等跳过;不一致抛错
326
+ * (组标识是业务关联键,形状漂移属调用方错误)
327
+ */
328
+ create(decl: TaskDriverGroupCreate): Promise<void>;
329
+ /**
330
+ * 记账一次成员落定(幂等——已落定成员重复 settle 计数不变)
331
+ *
332
+ * @param outcome 成员最终终态
333
+ * @returns 记账后快照;isLast = 本次落定后 settled >= total
334
+ * @throws 组不存在
335
+ */
336
+ settle(groupId: string, jobId: string, outcome: TaskGroupOutcome): Promise<TaskDriverGroupSettleResult>;
337
+ /** 逆向记账:成员重试回 pending 时撤销一次落定(成员未落定时 no-op) */
338
+ unsettle(groupId: string, jobId: string): Promise<void>;
339
+ /** 标记完成回调已入队(幂等) */
340
+ markCompletionEnqueued(groupId: string): Promise<void>;
341
+ /** 组快照;不存在返回 undefined */
342
+ get(groupId: string): Promise<TaskGroupSnapshot | undefined>;
343
+ /**
344
+ * fail-fast:取消组内未落定成员(等待/延迟中的不再执行;在跑的自然跑完),
345
+ * 实际取消成功的成员落定为 cancelled(幂等守卫防与运行实例的落定竞态重复计数),
346
+ * 返回记账后快照。对 run-to-completion 组为 no-op(返回当前快照)。
347
+ */
348
+ cancelRemaining(groupId: string): Promise<TaskGroupSnapshot>;
285
349
  }
286
350
 
287
351
  /**
@@ -448,7 +512,7 @@ declare function cors(options?: CorsOptions): FaapiMiddleware;
448
512
  *
449
513
  * 详见 [llmTypes.md](./llmTypes.md) 与 `@faapi/agent` 的 lightComplete.md。
450
514
  */
451
- /** 轻量补全的调用级选项——传输策略(重试/超时/降级/留痕)按场景声明 */
515
+ /** 轻量补全的调用级选项——传输策略(重试/超时/留痕)按场景声明 */
452
516
  interface LlmCompleteOptions {
453
517
  /**
454
518
  * 模型字符串 key(与 `agent.run` 的 `options.model` 同一解析规则):
@@ -467,7 +531,7 @@ interface LlmCompleteOptions {
467
531
  /**
468
532
  * 取消信号(透传到底层 HTTP 请求)
469
533
  *
470
- * abort 时抛 `AgentAbortError`——取消不是故障:不走 fallback、不触发 onFailure。
534
+ * abort 时抛 `AgentAbortError`——取消不是故障,不触发 onFailure。
471
535
  */
472
536
  signal?: AbortSignal;
473
537
  /**
@@ -484,22 +548,15 @@ interface LlmCompleteOptions {
484
548
  */
485
549
  maxRetries?: number;
486
550
  /**
487
- * 降级值:传输失败(重试耗尽)时返回本值而不抛
488
- *
489
- * 「LLM 失败可降级不可静默」——fallback 命中且未声明 `onFailure` 时,
490
- * 框架 `console.warn` 兜底留痕(错误消息含尝试次数)。
491
- * 未声明时失败原样抛 `LLMProviderError`。
492
- */
493
- fallback?: string;
494
- /**
495
- * 失败钩子:重试耗尽后触发(留痕/告警/台账等副作用;自身抛错被忽略)
551
+ * 失败钩子:重试耗尽后触发(留痕/告警/台账等副作用;自身抛错 console.error 留痕)
496
552
  *
497
553
  * - `error` 为 `LLMProviderError`(`instanceof LLMTimeoutError` 细分超时,
498
554
  * `error.status` 区分 HTTP 状态——502/504 分型等)
499
555
  * - `info.attempts` 为实际发起的 HTTP 尝试次数(含失败尝试,≥1)
500
556
  *
501
- * 声明本钩子后框架不再重复 `console.warn`(钩子即留痕点)。
502
- * 用户取消(`AgentAbortError`)不触发本钩子。
557
+ * 用户取消(`AgentAbortError`)不触发本钩子。框架不提供降级出口——传输失败
558
+ * 恒抛 `LLMProviderError`,需要降级语义的调用方在业务侧 try/catch 自行实现
559
+ * (降级是业务决策,不由框架代劳)。
503
560
  */
504
561
  onFailure?: (error: Error, info: {
505
562
  attempts: number;
@@ -517,7 +574,7 @@ interface LlmComplete {
517
574
  *
518
575
  * @returns assistant 消息 content(恒字符串;轻量通道不发 tools,LLM 不会请求 tool_call)
519
576
  * @throws {AgentError} model key 解析失败 / llms 未配置(编程/配置错误,不重试不降级)
520
- * @throws {LLMProviderError} 传输失败(重试耗尽)且未声明 `fallback`
577
+ * @throws {LLMProviderError} 传输失败(重试耗尽,含超时)——恒抛,无降级出口
521
578
  * @throws {AgentAbortError} 用户取消(`options.signal` 触发)
522
579
  */
523
580
  complete(input: string, options?: LlmCompleteOptions): Promise<string>;
@@ -921,7 +978,7 @@ interface LifecycleHooks {
921
978
  * → 响应发出后 → onError 触发副作用
922
979
  *
923
980
  * 职责:日志上报、告警、链路追踪等副作用。**不修改、不替换已生成的响应**。
924
- * 自身抛错会被捕获并忽略,不影响响应已发送的事实。
981
+ * 自身抛错会被捕获并 console.error 留痕,不影响响应已发送的事实。
925
982
  *
926
983
  * 与全局错误中间件的区别:
927
984
  * - 全局错误中间件:把 error 翻译成 Response(主入口,决定响应内容)
@@ -986,7 +1043,7 @@ interface TaskConfig {
986
1043
  /**
987
1044
  * 任务执行失败/取消钩子——每次 process 抛错后触发(含将重试的失败),
988
1045
  * `info.willRetry` 按任务 meta.retries 推算、`info.cancelled` 标记框架终止;
989
- * 用于告警/死信上报等副作用,自身抛错被忽略
1046
+ * 用于告警/死信上报等副作用,自身抛错 console.error 留痕
990
1047
  */
991
1048
  onFailed?: TaskFailedHandler;
992
1049
  }
@@ -1538,9 +1595,8 @@ interface TaskWorkerOptions {
1538
1595
  /** 任务产物模块绝对路径(`<dist>/tasks/<dir>/task.js`) */
1539
1596
  taskModulePath: string;
1540
1597
  payload: unknown;
1541
- /** signal 由执行器构造(abort/terminate 时触发),宿主只传 config 与 job 信息 */
1598
+ /** signal 由执行器构造(abort/terminate 时触发),宿主只传 job 信息 */
1542
1599
  taskCtx: {
1543
- config: unknown;
1544
1600
  /**
1545
1601
  * 产物 resources 目录绝对路径(纯字符串可结构化克隆)——经 workerData
1546
1602
  * 传给入口在任务模块求值前播种全局读取根(内部字段,不进业务 taskCtx)
@@ -1596,6 +1652,12 @@ interface TaskWorkerOptions {
1596
1652
  * 不传则日志条目被忽略。宽限期(取消判定后)到达的条目不采纳(超时判定即终局)
1597
1653
  */
1598
1654
  onLog?: (entry: LogEntry) => void;
1655
+ /**
1656
+ * 任务客户端 RPC 分派(worker 内 `taskCtx.tasks.*` 经 `{ type: 'tasks-call' }`
1657
+ * 消息回传宿主执行,结果/错误按 seq 回传)——语义层注入(闭包持有队列本体);
1658
+ * 不传则 worker 内 taskCtx.tasks 的调用以错误拒绝(直接构造执行器的测试场景)
1659
+ */
1660
+ onTasksCall?: (method: string, args: unknown[]) => Promise<unknown>;
1599
1661
  }
1600
1662
  declare function runTaskInWorker(options: TaskWorkerOptions): Promise<unknown>;
1601
1663
 
@@ -1665,6 +1727,49 @@ interface TaskMetadata {
1665
1727
  * 驱动重试时记录回到 running 继续流转。
1666
1728
  */
1667
1729
  type TaskJobStatus = 'pending' | 'running' | 'retry' | 'done' | 'failed' | 'cancelled';
1730
+ /**
1731
+ * 组内成员落定的终态(TaskJobStatus 的终态子集——落定 = 最终终态,
1732
+ * 重试等待中的失败不算)
1733
+ */
1734
+ type TaskGroupOutcome = 'done' | 'failed' | 'cancelled';
1735
+ /**
1736
+ * 组级失败语义(enqueueGroup 声明):
1737
+ * - 'run-to-completion'(默认):成员最终失败不影响其余成员,回调照常在全部落定时触发
1738
+ * - 'fail-fast':首个成员最终失败即取消组内未落定成员(在跑的自然跑完),取消成员落定 cancelled
1739
+ */
1740
+ type TaskGroupOnFailure = 'fail-fast' | 'run-to-completion';
1741
+ /**
1742
+ * 完成回调任务的 payload 契约(fan-in)——全部成员落定时框架以该形状入队
1743
+ * onComplete 任务(走 enqueue 同一 payload 校验通道,回调任务 Payload 声明须兼容,
1744
+ * 建议 `interface Payload extends TaskGroupSummary {}`)
1745
+ */
1746
+ interface TaskGroupSummary {
1747
+ /** 组标识(业务关联键原样透传) */
1748
+ groupId: string;
1749
+ /** 成员任务名 */
1750
+ task: string;
1751
+ /** 成员总数 */
1752
+ total: number;
1753
+ /** 按最终终态分桶计数 */
1754
+ done: number;
1755
+ failed: number;
1756
+ cancelled: number;
1757
+ /** 已落定数(done + failed + cancelled) */
1758
+ settled: number;
1759
+ }
1760
+ /**
1761
+ * 组记账快照(getGroup 返回;驱动侧存储的实时投影)
1762
+ */
1763
+ interface TaskGroupSnapshot extends TaskGroupSummary {
1764
+ /** 完成回调任务名(未声明时无 fan-in,仅记账) */
1765
+ onComplete?: string;
1766
+ /** 组级失败语义 */
1767
+ onFailure: TaskGroupOnFailure;
1768
+ /** 'settled' = 全部落定 */
1769
+ status: 'open' | 'settled';
1770
+ /** 完成回调是否已入队(false 且 status settled = 回调未入队——可经同 groupId 重投自愈) */
1771
+ completionEnqueued: boolean;
1772
+ }
1668
1773
  /**
1669
1774
  * 任务执行记录(内存快照)
1670
1775
  */
@@ -1681,6 +1786,8 @@ interface TaskJob {
1681
1786
  error?: string;
1682
1787
  /** 最近一次进度上报值(run 内 `taskCtx.progress(value)` 写入;派发时清空上一轮) */
1683
1788
  progress?: unknown;
1789
+ /** 所属任务组(组投递的成员任务携带;非组任务无此字段) */
1790
+ groupId?: string;
1684
1791
  createdAt: number;
1685
1792
  /** 计划执行时间戳(重试/延迟任务与 createdAt 不同) */
1686
1793
  runAt?: number;
@@ -1698,13 +1805,31 @@ interface TaskRegistriesSnapshot {
1698
1805
  skills: AgentCore[];
1699
1806
  }
1700
1807
  /**
1701
- * 传给任务 run 函数的第二参数
1808
+ * 进程内任务的 run 第二参数(默认路径——任务未声明 `timeoutMs` 时)
1809
+ *
1810
+ * 与 {@link IsolatedTaskContext} 显式分开:两条执行路径的行为差异是实质性的
1811
+ * (config 有无、registries 活引用 vs 快照、模块级状态共享 vs 独立、取消语义),
1812
+ * 由任务 meta 是否声明 `timeoutMs` 决定——业务按路径标注对应类型,边界编译期可见。
1702
1813
  */
1703
1814
  interface TaskContext {
1704
1815
  /** 优雅停机时对在跑任务 abort 的信号 */
1705
1816
  signal: AbortSignal;
1706
- /** faapi.config.ts 全量配置(含自定义业务配置) */
1707
- config: unknown;
1817
+ /**
1818
+ * 任务客户端(与 `ctx.tasks` / `app.tasks` 同一 app 实例队列)——任务内入队 /
1819
+ * 组投递 / 查询不绕 `getApp()`。隔离路径为 postMessage RPC 代理(语义一致,
1820
+ * 参数与返回值须可结构化克隆)
1821
+ */
1822
+ tasks: TaskClient;
1823
+ /**
1824
+ * faapi.config.ts 全量配置(含自定义业务配置),类型经 `FaapiContextConfig`
1825
+ * 声明合并增强——与 handler `ctx.config` 同一类型、同一对象(活引用)。
1826
+ * 业务增强的类型字段全部可读,函数字段可调用(同进程)。
1827
+ *
1828
+ * 仅进程内任务存在:隔离任务(声明 `timeoutMs`)的上下文类型
1829
+ * {@link IsolatedTaskContext} 没有此字段——worker 线程不接收进程配置,
1830
+ * 任务数据经 payload 显式传入。
1831
+ */
1832
+ config: FaapiContextConfig;
1708
1833
  job: {
1709
1834
  id: string;
1710
1835
  name: string;
@@ -1713,41 +1838,93 @@ interface TaskContext {
1713
1838
  /**
1714
1839
  * app 注册表只读视图(agent/tool/skill 元数据查询,不含 hydrate/clear 写接口)
1715
1840
  *
1716
- * 进程内执行为活引用;隔离执行为派发时刻的快照视图(worker 内重建)——
1717
- * 执行中途的 reload/DB skill 变更不影响当次执行。
1841
+ * 活引用(`createAppBase` 创建队列时传入)——反映注册表实时状态。
1718
1842
  * 任务内组装 agent 用 `registries.agent.getAgentEntry(name)`(含 filePath)。
1719
1843
  */
1720
1844
  registries: TaskRegistriesView;
1721
1845
  /**
1722
- * 进度上报(可选):执行中主动上报进度,记入 `TaskJob.progress`(`list()` 可见)
1723
- *
1724
- * 进程内直写记录;隔离路径经 postMessage 回传宿主(值必须可结构化克隆,
1725
- * 不可克隆按执行错误处理)。仅 running 状态生效,终态后调用被忽略。
1846
+ * 进度上报(可选):执行中主动上报进度,直写本进程任务记录
1847
+ * (`TaskJob.progress`,`list()` 可见)。仅 running 状态生效,终态后调用被忽略。
1726
1848
  */
1727
1849
  progress?: (value: unknown) => void;
1728
1850
  /**
1729
- * 任务级日志器(可选字段;框架两条执行路径均注入,直接构造 TaskContext 的
1730
- * 测试/自定义执行器可不传)——scope `task:<name>`,字段自动携带
1731
- * jobId/task/attempt,输出走 `config.log` 统一管道(详见 logger/logger.md)。
1732
- * 隔离执行时条目经 postMessage 回传宿主输出,fields 需可结构化克隆。
1851
+ * 任务级日志器(可选字段;框架注入,直接构造 TaskContext 的测试/自定义执行器
1852
+ * 可不传)——scope `task:<name>`,字段自动携带 jobId/task/attempt,直写
1853
+ * `config.log` 全局管道(详见 logger/logger.md)。
1733
1854
  */
1734
1855
  log?: Logger;
1735
1856
  /**
1736
1857
  * 轻量 LLM 补全通道(可选字段;`@faapi/agent` 插件加载且 `agent.llms` 可解析时注入)
1737
1858
  *
1738
- * 进程内执行为 `registries.llm` 的活引用(与 agent 循环共享 providers 单例);
1739
- * 隔离执行为 worker 内按 `agent.llms` 纯数据快照重建的实例(`@faapi/agent`
1740
- * 不可解析时为 `undefined`,warn 留痕不中断执行)。
1859
+ * `registries.llm` 的活引用(与 agent 循环共享 providers 单例)。
1741
1860
  * 一次性补全(分类/蒸馏/摘要等)用此通道,不必在任务内组装 agent;
1742
1861
  * 工具循环场景仍走 registries.agent 组装 Agent。详见 `@faapi/agent` 的 lightComplete.md。
1743
1862
  */
1744
1863
  llm?: LlmComplete;
1745
1864
  }
1865
+ /**
1866
+ * 隔离任务的 run 第二参数(任务声明 `timeoutMs` 时——独立 worker 线程执行)
1867
+ *
1868
+ * 与进程内 {@link TaskContext} 显式分开,差异由隔离语义决定:
1869
+ * - **没有 config 字段**——进程配置不跨线程(config 含函数字段不可结构化克隆,
1870
+ * 框架不做降级传递);任务数据经 payload 显式传入,`ctx.config` 是编译错误
1871
+ * - registries 为派发时刻的**快照**重建视图(执行中途 reload 不影响当次执行)
1872
+ * - llm 为 worker 内按 `agent.llms` 纯数据快照重建的实例
1873
+ * - log 条目经 postMessage 回传宿主统一输出(fields 须可结构化克隆,
1874
+ * 不可克隆按执行错误处理)
1875
+ * - progress 值经 postMessage 回传(须可结构化克隆,不可克隆按执行错误处理)
1876
+ * - 模块级状态每次执行独立;取消为两段式真终止(abort 宽限 → terminate 硬杀)
1877
+ */
1878
+ interface IsolatedTaskContext {
1879
+ /** 优雅停机时对在跑任务 abort 的信号(abort 后宽限期内未退出 terminate 硬杀) */
1880
+ signal: AbortSignal;
1881
+ /**
1882
+ * 任务客户端代理——全方法经 postMessage RPC 回传宿主执行(宿主走完整 enqueue
1883
+ * 通道:存在性检查 + payload 校验 + 驱动入队 + 本地记录),与进程内路径零语义差;
1884
+ * **参数与返回值须可结构化克隆**(不可克隆按执行错误处理,与 progress/log 同口径);
1885
+ * 挂起的调用随任务超时两段式取消一并终止,无独立超时
1886
+ */
1887
+ tasks: TaskClient;
1888
+ job: {
1889
+ id: string;
1890
+ name: string;
1891
+ attempt: number;
1892
+ };
1893
+ /**
1894
+ * app 注册表只读视图——**派发时刻的快照**在 worker 内重建(宿主生成
1895
+ * `TaskRegistriesSnapshot` 纯数据随 postMessage 传入),查询方法与活引用
1896
+ * 视图同型;执行中途的 reload/DB skill 变更不影响当次执行。
1897
+ */
1898
+ registries: TaskRegistriesView;
1899
+ /**
1900
+ * 进度上报(可选):值经 postMessage 回传宿主写入任务记录——**值必须可
1901
+ * 结构化克隆**,不可克隆按执行错误处理。仅 running 状态生效;取消判定后
1902
+ * (宽限期内)到达的上报忽略。
1903
+ */
1904
+ progress?: (value: unknown) => void;
1905
+ /**
1906
+ * 任务级日志器(可选字段;框架注入)——scope `task:<name>`,条目经 postMessage
1907
+ * 回传宿主走 `config.log` 统一管道;**fields 须可结构化克隆**(不可克隆按
1908
+ * 执行错误处理,与 progress 同语义)。
1909
+ */
1910
+ log?: Logger;
1911
+ /**
1912
+ * 轻量 LLM 补全通道(可选字段)——worker 内按 `agent.llms` 纯数据快照动态
1913
+ * 加载 `@faapi/agent` 重建;llms 已配置但不可解析时任务显式失败(含安装指引),
1914
+ * llms 未配置时为 `undefined`(能力不存在,非降级)。
1915
+ * 详见 `@faapi/agent` 的 lightComplete.md。
1916
+ */
1917
+ llm?: LlmComplete;
1918
+ }
1746
1919
  /**
1747
1920
  * 任务模块形态(task.ts 编译产物中与执行相关的导出)
1921
+ *
1922
+ * run 第二参数按执行路径二选一:进程内 {@link TaskContext} / 隔离
1923
+ * {@link IsolatedTaskContext}——路径由任务 meta 是否声明 `timeoutMs` 决定,
1924
+ * 业务标注对应类型后差异编译期可见(隔离上下文无 config 字段,访问即编译错误)。
1748
1925
  */
1749
1926
  interface TaskModule {
1750
- run?: (payload: unknown, taskCtx: TaskContext) => unknown;
1927
+ run?: (payload: unknown, taskCtx: TaskContext | IsolatedTaskContext) => unknown;
1751
1928
  }
1752
1929
  /**
1753
1930
  * 任务触发客户端(`tasks` 注入参数 / `ctx.tasks` / `app.tasks` 共用)
@@ -1792,6 +1969,40 @@ interface TaskClient {
1792
1969
  * @throws 驱动未实现 TaskDriver.retry
1793
1970
  */
1794
1971
  retry(name: string, id: string): Promise<void>;
1972
+ /**
1973
+ * 组投递:一次投递 N 个同构子任务并挂同一组标识(组投递 / 记账 / fan-in 完整
1974
+ * 语义见 taskGroups.md)
1975
+ *
1976
+ * - payloads 全量校验前置(任一失败整组不投递);空数组抛错
1977
+ * - opts.groupId 缺省自动生成;同 id 幂等重投(成员 dedupId 自动派生
1978
+ * `faapi-group:<groupId>:<index>`,替代业务自拼序号;长任务扇出建议 groupId
1979
+ * 从业务键派生——发起任务重试即天然补投自愈)
1980
+ * - opts.onComplete:全部成员落定时框架自动入队的回调任务名(payload =
1981
+ * TaskGroupSummary 契约);opts.onFailure:'fail-fast' | 'run-to-completion'
1982
+ * (缺省后者)
1983
+ *
1984
+ * @returns groupId 与各成员任务 id
1985
+ * @throws 任务不存在 / payloads 为空 / payload 校验失败(ValidationError)/
1986
+ * 队列已停止 / 驱动未实现组记账(TaskDriver.groups 缺失)
1987
+ */
1988
+ enqueueGroup(name: string, payloads: unknown[], opts?: {
1989
+ groupId?: string;
1990
+ onComplete?: string;
1991
+ onFailure?: TaskGroupOnFailure;
1992
+ delayMs?: number;
1993
+ }): Promise<{
1994
+ groupId: string;
1995
+ jobs: {
1996
+ id: string;
1997
+ }[];
1998
+ }>;
1999
+ /**
2000
+ * 组记账快照(计数器为驱动侧存储的实时投影——跨实例/重启正确)
2001
+ *
2002
+ * @returns 组不存在返回 undefined
2003
+ * @throws 驱动未实现组记账(TaskDriver.groups 缺失)
2004
+ */
2005
+ getGroup(groupId: string): Promise<TaskGroupSnapshot | undefined>;
1795
2006
  }
1796
2007
  /**
1797
2008
  * 任务队列(TaskClient + 生命周期控制,createAppBase 内部使用)
@@ -1812,8 +2023,8 @@ interface TaskQueue extends TaskClient {
1812
2023
  interface TaskQueueDeps {
1813
2024
  registry: TaskRegistry;
1814
2025
  rootDir: string;
1815
- /** faapi.config.ts 全量配置,透传给 run 的 TaskContext.config */
1816
- config?: unknown;
2026
+ /** faapi.config.ts 全量配置——注入进程内路径的 TaskContext.config(必填:无配置文件传空对象;隔离任务不传 config) */
2027
+ config: FaapiContextConfig;
1817
2028
  /**
1818
2029
  * 产物 resources 目录绝对路径——**内部字段**,仅作隔离 worker 读取根播种的
1819
2030
  * 数据源(经 workerData 传入 workerEntry,不进业务可见的 TaskContext——
@@ -2258,4 +2469,4 @@ interface FaapiContext {
2258
2469
  deleteCookie(name: string): void;
2259
2470
  }
2260
2471
 
2261
- export { type SseWriter as $, type AgentCore as A, type LlmComplete as B, type CreateLoggerOptions as C, type LlmCompleteOptions as D, type LlmConfig as E, type FaapiMiddleware as F, type LlmModelConfig as G, type HelmetOptions as H, type Injector as I, type LogEntry as J, type LogLevel as K, type LogConfig as L, type LogSink as M, type PluginDeclaration as N, type RequestHandler as O, type PluginContext as P, type ResponseConfig as Q, type RouteManifest as R, type RouteInfo as S, type TaskQueueDeps as T, type RouteInputSchema as U, type RouteOutputSchema as V, type WsRouteManifest as W, type RouteParamSchema as X, type SkillRegistry as Y, type SseEvent as Z, type SseOptions as _, type TaskQueue as a, type TaskBullMqOptions as a0, type TaskConfig as a1, type TaskContext as a2, type TaskDriverJob as a3, type TaskDriverProcess as a4, type TaskDriverRecord as a5, type TaskFailedHandler as a6, type TaskFailedInfo as a7, type TaskJob as a8, type TaskJobStatus as a9, type TaskMetadata as aa, type TaskModule as ab, type TaskPgBossOptions as ac, type TaskRegistriesSnapshot as ad, type TaskRegistriesView as ae, type ToolCore as af, type ToolPathMeta as ag, type ToolRegistry as ah, type UpgradeHandler as ai, cors as aj, createAppRegistries as ak, createTaskRegistriesView as al, createTaskRegistry as am, helmet as an, type TaskDriver as b, type TaskRegistry as c, type TaskManifest as d, type AgentMetadata as e, type ToolMetadata as f, type FaapiContext as g, type FaapiConfig as h, type Logger as i, type AppRegistries as j, type TaskClient as k, type AgentConfig as l, type AgentHandleFactory as m, type AgentHandleStore as n, type AgentPathMeta as o, type AgentRegistry as p, type AgentToolDescriptor as q, type CorsOptions as r, type FaapiContextConfig as s, type FaapiPlugin as t, type FaapiTaskMeta as u, type FailOptions as v, type InjectorMap as w, type LifecycleContext as x, type LifecycleHooks as y, type LlmChannelStore as z };
2472
+ export { type SseOptions as $, type AgentCore as A, type LlmChannelStore as B, type CreateLoggerOptions as C, type LlmComplete as D, type LlmCompleteOptions as E, type FaapiMiddleware as F, type LlmConfig as G, type HelmetOptions as H, type Injector as I, type LlmModelConfig as J, type LogEntry as K, type LogConfig as L, type LogLevel as M, type LogSink as N, type PluginDeclaration as O, type PluginContext as P, type RequestHandler as Q, type RouteManifest as R, type ResponseConfig as S, type TaskQueueDeps as T, type RouteInfo as U, type RouteInputSchema as V, type WsRouteManifest as W, type RouteOutputSchema as X, type RouteParamSchema as Y, type SkillRegistry as Z, type SseEvent as _, type TaskQueue as a, type SseWriter as a0, type TaskBullMqOptions as a1, type TaskConfig as a2, type TaskContext as a3, type TaskDriverGroupCreate as a4, type TaskDriverGroupOps as a5, type TaskDriverGroupSettleResult as a6, type TaskDriverJob as a7, type TaskDriverProcess as a8, type TaskDriverRecord as a9, type TaskFailedHandler as aa, type TaskFailedInfo as ab, type TaskGroupOnFailure as ac, type TaskGroupOutcome as ad, type TaskGroupSnapshot as ae, type TaskGroupSummary as af, type TaskJob as ag, type TaskJobStatus as ah, type TaskMetadata as ai, type TaskModule as aj, type TaskPgBossOptions as ak, type TaskRegistriesSnapshot as al, type TaskRegistriesView as am, type ToolCore as an, type ToolPathMeta as ao, type ToolRegistry as ap, type UpgradeHandler as aq, cors as ar, createAppRegistries as as, createTaskRegistriesView as at, createTaskRegistry as au, helmet as av, type TaskDriver as b, type TaskRegistry as c, type TaskManifest as d, type AgentMetadata as e, type ToolMetadata as f, type FaapiContext as g, type FaapiConfig as h, type Logger as i, type AppRegistries as j, type TaskClient as k, type AgentConfig as l, type AgentHandleFactory as m, type AgentHandleStore as n, type AgentPathMeta as o, type AgentRegistry as p, type AgentToolDescriptor as q, type CorsOptions as r, type FaapiContextConfig as s, type FaapiPlugin as t, type FaapiTaskMeta as u, type FailOptions as v, type InjectorMap as w, type IsolatedTaskContext as x, type LifecycleContext as y, type LifecycleHooks as z };
package/dist/index.d.ts CHANGED
@@ -1,5 +1,5 @@
1
- import { F as FaapiMiddleware, R as RouteManifest, W as WsRouteManifest, T as TaskQueueDeps, a as TaskQueue, b as TaskDriver, c as TaskRegistry, d as TaskManifest, A as AgentCore, e as AgentMetadata, f as ToolMetadata, g as FaapiContext, h as FaapiConfig, L as LogConfig, C as CreateLoggerOptions, i as Logger, j as AppRegistries, k as TaskClient } from './contextTypes-WKsf3cCE.js';
2
- export { l as AgentConfig, m as AgentHandleFactory, n as AgentHandleStore, o as AgentPathMeta, p as AgentRegistry, q as AgentToolDescriptor, r as CorsOptions, s as FaapiContextConfig, t as FaapiPlugin, u as FaapiTaskMeta, v as FailOptions, H as HelmetOptions, I as Injector, w as InjectorMap, x as LifecycleContext, y as LifecycleHooks, z as LlmChannelStore, B as LlmComplete, D as LlmCompleteOptions, E as LlmConfig, G as LlmModelConfig, J as LogEntry, K as LogLevel, M as LogSink, P as PluginContext, N as PluginDeclaration, O as RequestHandler, Q as ResponseConfig, S as RouteInfo, U as RouteInputSchema, V as RouteOutputSchema, X as RouteParamSchema, Y as SkillRegistry, Z as SseEvent, _ as SseOptions, $ as SseWriter, a0 as TaskBullMqOptions, a1 as TaskConfig, a2 as TaskContext, a3 as TaskDriverJob, a4 as TaskDriverProcess, a5 as TaskDriverRecord, a6 as TaskFailedHandler, a7 as TaskFailedInfo, a8 as TaskJob, a9 as TaskJobStatus, aa as TaskMetadata, ab as TaskModule, ac as TaskPgBossOptions, ad as TaskRegistriesSnapshot, ae as TaskRegistriesView, af as ToolCore, ag as ToolPathMeta, ah as ToolRegistry, ai as UpgradeHandler, aj as cors, ak as createAppRegistries, al as createTaskRegistriesView, am as createTaskRegistry, an as helmet } from './contextTypes-WKsf3cCE.js';
1
+ import { F as FaapiMiddleware, R as RouteManifest, W as WsRouteManifest, T as TaskQueueDeps, a as TaskQueue, b as TaskDriver, c as TaskRegistry, d as TaskManifest, A as AgentCore, e as AgentMetadata, f as ToolMetadata, g as FaapiContext, h as FaapiConfig, L as LogConfig, C as CreateLoggerOptions, i as Logger, j as AppRegistries, k as TaskClient } from './contextTypes-Bsc1ljvn.js';
2
+ export { l as AgentConfig, m as AgentHandleFactory, n as AgentHandleStore, o as AgentPathMeta, p as AgentRegistry, q as AgentToolDescriptor, r as CorsOptions, s as FaapiContextConfig, t as FaapiPlugin, u as FaapiTaskMeta, v as FailOptions, H as HelmetOptions, I as Injector, w as InjectorMap, x as IsolatedTaskContext, y as LifecycleContext, z as LifecycleHooks, B as LlmChannelStore, D as LlmComplete, E as LlmCompleteOptions, G as LlmConfig, J as LlmModelConfig, K as LogEntry, M as LogLevel, N as LogSink, P as PluginContext, O as PluginDeclaration, Q as RequestHandler, S as ResponseConfig, U as RouteInfo, V as RouteInputSchema, X as RouteOutputSchema, Y as RouteParamSchema, Z as SkillRegistry, _ as SseEvent, $ as SseOptions, a0 as SseWriter, a1 as TaskBullMqOptions, a2 as TaskConfig, a3 as TaskContext, a4 as TaskDriverGroupCreate, a5 as TaskDriverGroupOps, a6 as TaskDriverGroupSettleResult, a7 as TaskDriverJob, a8 as TaskDriverProcess, a9 as TaskDriverRecord, aa as TaskFailedHandler, ab as TaskFailedInfo, ac as TaskGroupOnFailure, ad as TaskGroupOutcome, ae as TaskGroupSnapshot, af as TaskGroupSummary, ag as TaskJob, ah as TaskJobStatus, ai as TaskMetadata, aj as TaskModule, ak as TaskPgBossOptions, al as TaskRegistriesSnapshot, am as TaskRegistriesView, an as ToolCore, ao as ToolPathMeta, ap as ToolRegistry, aq as UpgradeHandler, ar as cors, as as createAppRegistries, at as createTaskRegistriesView, au as createTaskRegistry, av as helmet } from './contextTypes-Bsc1ljvn.js';
3
3
  import ts from 'typescript';
4
4
  import { Server } from 'node:http';
5
5
  import 'node:net';