@aalis/api-hooks 0.2.0 → 0.4.0

package/README.md

@@ -10,18 +10,13 @@
 
 ## 顺序
 
-链内按登记顺序执行。登记序是每条登记自带的序号，提供者按它排链：以更高优先级换上另一个提供者时，各插件的登记整批重挂，链序不变。提供者重启时，依赖它的插件随之重启并重新登记，链序即重新激活的次序，与冷启动相同。相位内的 handler 应与顺序无关。
+链内按登记方的位次排：宿主自己登记的最前，插件按实例 id 的码元序，同一个插件登记的几条按登记先后。链序不看登记发生的时刻：插件重启、提供者重启或换人都不改变它。相位内的 handler 应与顺序无关。
 
-自己实现提供者时，`register` 须按 `order` 升序插入。
+自己实现提供者时，`register` 须按（`seat`，`order`）插入：先比 `seat` 的码元序，同一 `seat` 按 `order` 升序；交给每个中间件的 `next` 只许调一次，再调须拒绝。
 
 ## 运行中换提供者的已知现状
 
-以更高优先级上线第二个钩子提供者，或在 WebUI 设置「系统」的服务偏好里切换 hooks 时，有两种情形会让截停者暂时缺席：
-
-- 换人那一刻正在执行的链会跳过已移到新提供者的中间件。被跳过的若是截停者，默认动作照样执行。
-- 胜者在容器里同步换人，各插件的登记要逐个重挂到新提供者上。重挂完成前新发起的链，只能看到已经搬过来的中间件。
-
-两种情形都只发生在运行中换提供者的那一刻。第一方部署只有 `@aalis/plugin-hooks` 一个提供者，不会遇到。
+以更高优先级上线第二个钩子提供者，或在 WebUI 设置「系统」的服务偏好里切换 hooks 时，换人那一刻正在执行的链会跳过已移到新提供者的中间件。被跳过的若是截停者，默认动作照样执行。第一方部署只有 `@aalis/plugin-hooks` 一个提供者，不会遇到。
 
 ## 安装
 

package/dist/index.d.ts

@@ -1,7 +1,7 @@
 /** 钩子扩展点（空接口；由各 -api 包经 declaration merging 注入「钩子名 → 中间件上下文」） */
 export interface HookContextMap {
 }
-/** 中间件 next：把控制交给下一个中间件或默认动作 */
+/** 中间件 next：把控制交给下一个中间件或默认动作。一个中间件里只能调一次，再调返回被拒的 Promise */
 export type MiddlewareNext = () => Promise<void>;
 /** 中间件：可改 data（引用传递），调 next() 继续，不调即截停（含默认动作） */
 export type MiddlewareFn<T> = (data: T, next: MiddlewareNext) => Promise<void>;
@@ -16,16 +16,17 @@ export interface RunOptions {
  */
 export interface HookRegistry {
     /**
-     * 按 order 升序插入该钩子链。order 是门面在登记时分配的登记序（进程内全部 api-hooks 副本共用一个计数器，单调递增），换提供者重挂时原样带过来，
-     * 提供者据它还原原来的交错次序。contextId 供卡链告警点名。返回退订（幂等，只撤这一条）
+     * 按（seat，order）插入该钩子链：先比 seat 的码元序，同一 seat 按 order 升序。seat 是登记方的位次（宿主的根是空串，
+     * 插件是它的实例 id），order 是门面在登记时分配的登记序（进程内全部 api-hooks 副本共用一个计数器，单调递增）。
+     * 两者在换提供者重挂时原样带过来，次序不看登记发生的时刻。contextId 供卡链告警点名。返回退订（幂等，只撤这一条）
      */
-    register(hook: string, fn: MiddlewareFn<unknown>, contextId: string, order: number): () => void;
+    register(hook: string, fn: MiddlewareFn<unknown>, contextId: string, order: number, seat: string): () => void;
     /** 驱动一条钩子链；true = 走到底（含执行了默认动作或本就没有 handler），false = 被截停 */
     run(hook: string, data: unknown, defaultAction?: () => Promise<void>, opts?: RunOptions): Promise<boolean>;
 }
 /** `hooks` 的绑定接口 */
 export interface Hooks {
-    /** 注册中间件（洋葱模型，按登记顺序）；返回退订，随这次激活撤回 */
+    /** 注册中间件（洋葱模型，按登记方的位次，同一登记方按登记先后）；返回退订，随这次激活撤回 */
     middleware<K extends string & keyof HookContextMap>(hook: K, fn: MiddlewareFn<HookContextMap[K]>): () => void;
     /** 驱动一条钩子链；返回 false 表示被某个中间件截停 */
     run<K extends string & keyof HookContextMap>(hook: K, data: HookContextMap[K], defaultAction?: () => Promise<void>, opts?: RunOptions): Promise<boolean>;

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAkBA,iEAAiE;AACjE,MAAM,WAAW,cAAc;CAAG;AAElC,gCAAgC;AAChC,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjD,iDAAiD;AACjD,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/E,gBAAgB;AAChB,MAAM,WAAW,UAAU;IACzB,sDAAsD;IACtD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;OAGG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAChG,4DAA4D;IAC5D,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5G;AAED,oBAAoB;AACpB,MAAM,WAAW,KAAK;IACpB,qCAAqC;IACrC,UAAU,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,cAAc,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IAC9G,kCAAkC;IAClC,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,cAAc,EACzC,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EACnC,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAWD,eAAO,MAAM,KAAK,8DAYhB,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAiBA,iEAAiE;AACjE,MAAM,WAAW,cAAc;CAAG;AAElC,4DAA4D;AAC5D,MAAM,MAAM,cAAc,GAAG,MAAM,OAAO,CAAC,IAAI,CAAC,CAAC;AAEjD,iDAAiD;AACjD,MAAM,MAAM,YAAY,CAAC,CAAC,IAAI,CAAC,IAAI,EAAE,CAAC,EAAE,IAAI,EAAE,cAAc,KAAK,OAAO,CAAC,IAAI,CAAC,CAAC;AAE/E,gBAAgB;AAChB,MAAM,WAAW,UAAU;IACzB,sDAAsD;IACtD,WAAW,CAAC,EAAE,OAAO,CAAC;CACvB;AAED;;;GAGG;AACH,MAAM,WAAW,YAAY;IAC3B;;;;OAIG;IACH,QAAQ,CAAC,IAAI,EAAE,MAAM,EAAE,EAAE,EAAE,YAAY,CAAC,OAAO,CAAC,EAAE,SAAS,EAAE,MAAM,EAAE,KAAK,EAAE,MAAM,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,IAAI,CAAC;IAC9G,4DAA4D;IAC5D,GAAG,CAAC,IAAI,EAAE,MAAM,EAAE,IAAI,EAAE,OAAO,EAAE,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EAAE,IAAI,CAAC,EAAE,UAAU,GAAG,OAAO,CAAC,OAAO,CAAC,CAAC;CAC5G;AAED,oBAAoB;AACpB,MAAM,WAAW,KAAK;IACpB,kDAAkD;IAClD,UAAU,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,cAAc,EAAE,IAAI,EAAE,CAAC,EAAE,EAAE,EAAE,YAAY,CAAC,cAAc,CAAC,CAAC,CAAC,CAAC,GAAG,MAAM,IAAI,CAAC;IAC9G,kCAAkC;IAClC,GAAG,CAAC,CAAC,SAAS,MAAM,GAAG,MAAM,cAAc,EACzC,IAAI,EAAE,CAAC,EACP,IAAI,EAAE,cAAc,CAAC,CAAC,CAAC,EACvB,aAAa,CAAC,EAAE,MAAM,OAAO,CAAC,IAAI,CAAC,EACnC,IAAI,CAAC,EAAE,UAAU,GAChB,OAAO,CAAC,OAAO,CAAC,CAAC;CACrB;AAWD,eAAO,MAAM,KAAK,8DAYhB,CAAC"}

package/dist/index.js

@@ -2,10 +2,9 @@
 // @aalis/api-hooks — 钩子契约
 //
 // 每个钩子键代表一个语义清晰的生命周期事件（如 inbound:command / agent:llm:before），
-// handler 在事件内部按**登记顺序**串行执行洋葱模型（next 交棒）。不用数字 priority：
-// 相位之间的次序由调度方显式表达；相位内部的 handler 应顺序无关，或由相位拥有方约定。
-// 登记序是每条登记自带的序号，提供者按它排链：换提供者时各账本整批重挂，链序不变；
-// 提供者重启时依赖方随之重启、重新登记，链序即重新激活的次序（与冷启动相同）。
+// handler 在事件内部串行执行洋葱模型（next 交棒），按登记方的位次排（宿主的根最前，插件按实例 id 的码元序），同一登记方的几条按登记先后。
+// 不用数字 priority：相位之间的次序由调度方显式表达；相位内部的 handler 应顺序无关，或由相位拥有方约定。
+// 链序不看登记发生的时刻：插件重启、提供者重启或换人都不改变它。
 // 默认提供者：@aalis/plugin-hooks。没有提供者时 run 返回被拒的 Promise（不执行默认动作）。
 //
 // 钩子键由各 -api 包经 declaration merging 注入 HookContextMap：
@@ -16,18 +15,18 @@
 import { defineService } from '@aalis/core';
 /**
  * 登记序计数器：进程内全部 api-hooks 副本共用一个（经全局符号表取同一个对象），登记即取号。
- * 契约包可能装了两份，各自从 0 计数的话序号不可比，提供者按序排链就会把后登记的排到前面。
+ * 契约包可能装了两份：各自计数的话，同一个登记方经两份登记的几条序号不可比，提供者排链时会把后登记的排到前面。
  */
 const ORDER = Symbol.for('@aalis/api-hooks.order');
 const shared = globalThis;
 shared[ORDER] ??= { n: 0 };
 const orderCounter = shared[ORDER];
 export const hooks = defineService('hooks', port => {
-    // 每次登记一个独立账目：同一激活可在同一钩子上挂多个 handler，没有「同键替换」。登记序全局唯一，
-    // 用作账本键不会撞；键带钩子名，关闭后登记的告警能点名
+    // 每次登记一个独立条目：同一激活可在同一钩子上挂多个 handler，没有「同键替换」。登记序全局唯一，
+    // 用作归属表的键不会撞；键带钩子名，关闭后登记的告警能点名
     const ledger = port.registrar({
         key: ({ hook, order }) => `${hook}#${order}`,
-        register: (registry, { hook, fn, order }) => registry.register(hook, fn, port.id, order),
+        register: (registry, { hook, fn, order }) => registry.register(hook, fn, port.id, order, port.seat),
     });
     return {
         middleware: (hook, fn) => ledger.add({ hook, fn: fn, order: ++orderCounter.n }),

package/dist/index.js.map

@@ -1 +1 @@
-{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,0BAA0B;AAC1B,EAAE;AACF,8DAA8D;AAC9D,yDAAyD;AACzD,iDAAiD;AACjD,2CAA2C;AAC3C,yCAAyC;AACzC,+DAA+D;AAC/D,EAAE;AACF,uDAAuD;AACvD,wCAAwC;AACxC,wEAAwE;AACxE,MAAM;AACN,+DAA+D;AAE/D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA4C5C;;;GAGG;AACH,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;AACnD,MAAM,MAAM,GAAG,UAAuD,CAAC;AACvE,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AAC3B,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;AAEnC,MAAM,CAAC,MAAM,KAAK,GAAG,aAAa,CAAsB,OAAO,EAAE,IAAI,CAAC,EAAE;IACtE,sDAAsD;IACtD,6BAA6B;IAC7B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAA6D;QACxF,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,KAAK,EAAE;QAC5C,QAAQ,EAAE,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,CAAC;KACzF,CAAC,CAAC;IACH,OAAO;QACL,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,EAA2B,EAAE,KAAK,EAAE,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC;QACxG,yDAAyD;QACzD,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC;KACnG,CAAC;AACJ,CAAC,CAAC,CAAC"}
+{"version":3,"file":"index.js","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,+DAA+D;AAC/D,0BAA0B;AAC1B,EAAE;AACF,8DAA8D;AAC9D,+EAA+E;AAC/E,+DAA+D;AAC/D,kCAAkC;AAClC,+DAA+D;AAC/D,EAAE;AACF,uDAAuD;AACvD,wCAAwC;AACxC,wEAAwE;AACxE,MAAM;AACN,+DAA+D;AAE/D,OAAO,EAAE,aAAa,EAAE,MAAM,aAAa,CAAC;AA6C5C;;;GAGG;AACH,MAAM,KAAK,GAAG,MAAM,CAAC,GAAG,CAAC,wBAAwB,CAAC,CAAC;AACnD,MAAM,MAAM,GAAG,UAAuD,CAAC;AACvE,MAAM,CAAC,KAAK,CAAC,KAAK,EAAE,CAAC,EAAE,CAAC,EAAE,CAAC;AAC3B,MAAM,YAAY,GAAG,MAAM,CAAC,KAAK,CAAC,CAAC;AAEnC,MAAM,CAAC,MAAM,KAAK,GAAG,aAAa,CAAsB,OAAO,EAAE,IAAI,CAAC,EAAE;IACtE,sDAAsD;IACtD,+BAA+B;IAC/B,MAAM,MAAM,GAAG,IAAI,CAAC,SAAS,CAA6D;QACxF,GAAG,EAAE,CAAC,EAAE,IAAI,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,GAAG,IAAI,IAAI,KAAK,EAAE;QAC5C,QAAQ,EAAE,CAAC,QAAQ,EAAE,EAAE,IAAI,EAAE,EAAE,EAAE,KAAK,EAAE,EAAE,EAAE,CAAC,QAAQ,CAAC,QAAQ,CAAC,IAAI,EAAE,EAAE,EAAE,IAAI,CAAC,EAAE,EAAE,KAAK,EAAE,IAAI,CAAC,IAAI,CAAC;KACpG,CAAC,CAAC;IACH,OAAO;QACL,UAAU,EAAE,CAAC,IAAI,EAAE,EAAE,EAAE,EAAE,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,IAAI,EAAE,EAAE,EAAE,EAA2B,EAAE,KAAK,EAAE,EAAE,YAAY,CAAC,CAAC,EAAE,CAAC;QACxG,yDAAyD;QACzD,GAAG,EAAE,KAAK,EAAE,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,EAAE,EAAE,CAAC,IAAI,CAAC,QAAQ,CAAC,GAAG,CAAC,IAAI,EAAE,IAAI,EAAE,aAAa,EAAE,IAAI,CAAC;KACnG,CAAC;AACJ,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@aalis/api-hooks",
-  "version": "0.2.0",
+  "version": "0.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -21,10 +21,10 @@
   "devDependencies": {
     "@types/node": "^22.0.0",
     "typescript": "^5.7.0",
-    "@aalis/core": "0.20.0"
+    "@aalis/core": "0.22.0"
   },
   "peerDependencies": {
-    "@aalis/core": ">=0.20.0 <1.0.0"
+    "@aalis/core": ">=0.22.0 <1.0.0"
   },
   "keywords": [
     "aalis",