问题域/PD-10

中间件管道

Middleware Pipeline

Agent 生命周期中横切关注点的可组合中间件解耦。日志、限流、缓存等通过中间件注入。

子问题

1.中间件注册：如何定义和注册中间件

2.执行顺序：中间件的执行顺序和优先级

3.上下文传递：中间件间如何传递上下文

4.错误处理：中间件异常不影响主流程

5.可组合性：中间件可自由组合和拆卸

6.声明式规则 DSL：YAML 定义 trigger/accumulator/signal 三段式规则的表达力与扩展性

7.滑动窗口聚合：环形缓冲区纯函数实现高频事件计数与阈值触发

8.信号过滤转发：反射层按信号类型决定是否转发给意识层（LLM）的路由策略

9.行为竞选评分：多行为按 score/cooldown/mode 三维度竞争执行权的仲裁机制

10.TypeScript 逃生舱：声明式规则表达力不足时的编程式扩展接口设计

11.事件因果链追踪：AsyncLocalStorage 自动传播 traceId 实现跨层因果链

12.Prompt 层级优先级：多层 prompt 拼接时如何保证后层覆盖前层的语义优先级

13.Hook 脚本 jq 依赖：目标环境无 jq 时的 fallback 解析策略

14.反应配置合并：全局默认反应与项目级覆盖的合并规则（浅合并 vs 深合并）

15.通知优先级路由：不同严重度事件如何分发到不同通知渠道

16.全局完成一次性触发：所有 session 终态时如何确保汇总通知只发一次

17.反应配置合并：项目级覆盖全局级反应配置的合并策略

18.PR 自动发现：Agent 无 Hook 时通过分支名反向查找 PR

19.反应升级策略：重试次数 vs 时间窗口的双维度升级判定

20.跨插件状态探测：多插件按优先级链式探测 session 真实状态

21.元数据回流：agent 内部信息如何通过 Hook 回传到编排层

22.轮询重入保护：定时轮询如何防止上一轮未完成时重复执行

23.全局完成检测：所有 session 终态时的一次性汇总通知

24.双层 Hook 协同：Toolkit 中间件和 Agent Hook 如何协同工作而不冲突

25.元类包装时机：如何在类定义时自动包装而不影响子类继承

26.流式中断恢复：AsyncGenerator 被中断后如何注入中断消息并优雅退出

27.参数归一化成本：每次 Hook 调用都需要 inspect.signature 绑定参数的性能开销

28.Hook 执行顺序可见性：如何让开发者清楚地知道 Hook 的执行顺序

29.中间件闭包捕获：reversed 循环中如何避免闭包变量绑定问题

30.平台 I/O 归一化：不同 IDE 的 stdin/stdout JSON 格式差异如何统一

31.退出码语义映射：Hook 进程退出码如何精确传递成功/降级/错误三种状态

32.stdin 不关闭问题：宿主进程不发送 EOF 时如何可靠读取完整 JSON 输入

33.Hook 链前置守卫：多步 hook 链中如何确保依赖服务（Worker）已就绪

34.运行时类变更安全性：__class__ 赋值改变实例类型时的方法解析顺序（MRO）风险

35.多定价模型统一：per-token 和 flat-rate 两种 API 计费模式的统一追踪接口

36.迭代超限善后：Agent 达到迭代上限时如何自动收集和提交已有产出物

37.成本摘要注入位置：在响应末尾追加 vs 通过 metadata 传递 vs 独立通知渠道

38.双层去抖编排：无文本内容缓冲与时间窗口去抖的先后顺序和交互

39.Channel 热替换：运行时替换 Channel 实例时如何保证队列和 worker 的连续性

40.自定义 Channel 发现：从文件系统动态加载第三方 Channel 类的安全性和命名冲突

41.session 级串行保证：多 worker 并发下同 session 消息的 drain-batch-process 原子性

42.子代理中间件栈继承：子代理如何自动获得基础中间件栈并允许追加自定义中间件

43.大结果驱逐策略：工具返回超大结果时如何自动写入文件系统并替换为截断预览

44.PrivateStateAttr 隔离：中间件私有状态如何防止泄漏到子代理

45.Backend 工厂延迟创建：中间件接受实例或工厂函数以适配不同 backend 生命周期

46.异步交互桥接：插件需要等待前端用户响应时的 Future/Promise 模式

47.装饰器包装：不修改原函数代码直接注入 before/after hook 的高阶函数模式

48.超时降级策略：用户无响应时的 auto-skip vs auto-approve 选择

49.悬挂工具调用修复：用户中断导致 AIMessage.tool_calls 无对应 ToolMessage 时的自动补丁策略

50.去抖记忆更新：高频对话场景下中间件如何通过 Timer 去抖避免频繁 LLM 调用

51.子代理调用截断：LLM 输出过多并行 task 调用时的 after_model 硬截断 vs prompt 软限制

52.多模态条件注入：仅在模型支持 vision 时动态添加图片注入中间件

53.Reducer 清除语义：空 dict 作为清除信号的约定（merge_viewed_images 空 dict 清除全部）

54.懒初始化策略：中间件资源获取的 eager vs lazy 时机选择

55.状态切片类型安全：泛型参数声明中间件所需状态字段子集

56.augmenter 串联：检测器管道执行后如何串联多个纯函数增强器扩展 findings

57.泛型插件工厂：如何将外部工具规格一站式转化为检测器+评分策略+修复器三件套

58.profile 驱动阶段裁剪：objective/full/ci 三种扫描模式如何复用同一 phase 列表

59.置信度驱动停止：LLM 评估每轮检索充分度，动态决定是否继续迭代

60.自适应参数调整：根据查询复杂度和仓库规模动态调整迭代轮数、置信度阈值和行数预算

61.加权合并归一化：不同量纲的搜索分数（向量相似度 vs BM25）如何归一化后加权融合

62.双模管道切换：同一入口根据配置分发到标准串行管道或迭代管道的路由设计

63.迭代效率评估：ROI（置信度增益/行数增量）和效率评级的量化指标体系

64.递归依赖补全：拦截器内递归执行缺失前置节点的深度控制与循环检测

65.媒体 base64 序列化：跨进程传输大文件时的压缩编码与 MD5 校验

66.MCP vs Skill 错误判断分歧：不同工具类型的 isError 字段位置和语义不统一

67.拦截器列表差异：CLI 和 FastAPI 入口注册不同数量的拦截器的一致性管理

68.渐进式数据缩减：多阶段逐步过滤减少下游 AI 调用量的成本优化策略

69.双层去重时机：URL 精确去重在 AI 前、语义去重在 AI 后的阶段编排考量

70.富化子管道嵌套：管道阶段内部再嵌套多步 AI 子管道的组织方式

71.多语言并行输出：同一管道结果按配置语言列表生成多份输出的循环策略

72.插件路由冲突检测：第三方插件注册路由时如何防止覆盖核心 API 端点

73.客户端断连资源回收：长时间 LLM 推理期间客户端断连后如何取消计算任务

74.ASGI receive 拦截 vs BaseHTTPMiddleware：何时选择低层 ASGI 原生 vs 高层抽象

75.multipart 边界校验：上传请求的 boundary 格式验证防止畸形请求穿透

76.ContextVar 跨线程传播：asyncio ContextVar 不自动传播到 ThreadPoolExecutor worker，需自定义 submit 包装

77.多 API 入口 source 区分：同一中间件类通过构造参数标识请求来源（product_api vs server_api）

78.限流客户端标识优先级：API Key 前缀 vs X-Forwarded-For vs client.host 的选择策略

79.认证粒度选择：中间件级全局拦截 vs 依赖注入级路由粒度控制的权衡

80.日志上下文注入：logging.Filter 从 ContextVar 读取字段注入日志记录的线程安全问题

81.读写 API 分离注册：同一环境的读操作和写操作如何用独立注册表管理

82.多 react 模式切换：同一 Role 类如何在 ReAct/ByOrder/PlanAndAct 间动态切换

83.LLM 输出多步修复：大小写/标签/JSON/解析四步串行修复的插件可覆写设计

84.消息回滚重试：管道异常时如何回滚已观察消息使其可被重新处理

85.熔断器冷却恢复：自动禁用的 handler 何时重新启用的时间窗口策略

86.Shell Hook stdin 写入容错：子进程不读 stdin 时 BrokenPipe 的静默处理

87.HOOK.md 资格检查：OS/二进制依赖/环境变量三维资格校验与 UI 展示

88.内置 hook vs 外部 hook 注册顺序：编译期 Rust hook 与运行时 shell hook 的优先级协调

89.同步与异步混合：热路径 hook 必须同步执行，如何防止插件误用 async

90.结果合并策略：多插件返回冲突结果时的合并规则（first-wins/last-wins/拼接/error优先）

91.全局单例生命周期：hook runner 的初始化时机和全局访问模式

92.Observer 穿透查询：Observer 需要穿透到 Handler 内部获取 DAG 统计等深层数据

93.永远健康组件适配：部分子系统无健康状态概念时如何适配统一接口

94.环形错误缓冲区容量：错误记录的保留数量与内存占用的平衡策略

95.懒实例化 vs 缓存：每次 new Observer 的开销与缓存过期数据的风险权衡

96.段落 ID 稳定性：流式 chunk 如何共享同一个 item_id 贯穿整个段落生命周期

97.边界触发 flush：immediate 事件到达时如何自动清空同上下文的 buffered 内容保证时序

98.双向序列化：持久化记录如何反向重建为内存中的类型化响应对象

99.SideEffect 指令模式：路由层如何通过返回指令而非直接操作来保持纯函数特性

100.薄垫片版本同步：Git Hook 脚本仅 20 行委托调用，升级 CLI 自动更新 Hook 逻辑

101.外部管理器冲突：检测 lefthook/husky/pre-commit 后自动重命名为 .old 并链式调用

102.跨平台进程清理：Unix 用 Setpgid + kill(-pid) 终止进程组，Windows 用 Process.Kill 终止主进程

103.双层 Hook 协同：应用层 Hook 异步扩展业务逻辑，Git Hook 同步保证工作流一致性

104.Hook 版本检测：通过脚本头部标记（# tool-shim v2）判断 Hook 是否过时

105.matcher 自动正则检测：如何根据字符串内容自动判断使用精确匹配还是正则匹配

106.Hook 类型与 matcher 支持矩阵：哪些 Hook 类型支持 matcher 过滤，哪些始终执行

107.工具别名穿透匹配：matcher 需同时检查工具原名和所有别名的匹配策略

108.Notification 退出码 2 旁路语义：不阻断通知显示但展示 stderr 的特殊处理

109.会话启动源匹配：SessionStart Hook 按 startup/resume/clear/compress 四种源过滤

110.步骤依赖静态校验：注册时验证 requires/produces 链完整性避免运行时缺键

111.管道版本化修订：每次 insert/replace/remove 创建新 revision 支持审计回溯

112.步骤级 LLM Profile 路由：同一管道内不同步骤通过 config 使用不同模型

113.可插拔执行后端：WorkflowRunner Protocol 支持 local/Temporal/Burr 等后端切换

114.能力声明校验：步骤 capabilities 在注册时校验是否在可用能力集内

115.媒介类型翻译：同一摄影参数在不同媒介（真人/动画/定格/抽象）下的等效语义表达

116.摄影档案回退链：项目级默认值与逐镜覆盖的多字段回退策略

117.组级横切关注点注入：引用收集、时间轴、对白唇形同步等跨镜头关注点的组装位置

118.API 配额前置校验：在 prompt 组装前完成资源引用的配额检查避免后置截断

119.插件竞争选举：多个同类插件同时激活时的优先级仲裁策略

120.进程级作用域：不同插件组在多进程架构中的加载时机和可见范围

121.模型驱动激活：由模型配置而非全局配置决定哪个处理器插件被激活

122.副作用注册模式：插件通过执行副作用（注册到全局 Registry）而非返回值生效

123.节点预算权重分配：不同节点按角色分配 Token 预算比例的策略

124.三层递进压缩：embedding筛选→LLM压缩→全量摘要的分层降级压缩

125.并行节点状态合并：多节点并行写入同一字段时的 reducer 注册表模式

126.声明式功能开关：环境变量+StyleProfile 双开关的 TOGGLE_MAP 声明式管理

各项目的解法29 solutions

Signals

横向对比

维度DeerFlowAIRIAgentAgentOrchestratorAgentScopeclaude-memClawWorkCoPawDeepAgentsDeepCodeDeepTutorDesloppifyFastCodeFireRed-OpenStorylineHorizonLangflowMemOSMetaGPTMoltisOpenClawOpenVikingValueCellbeadsiflow-climemUmoyin-creatorseedance-2vLLMvibe-blog
中间件基类AgentMiddleware[S] 泛型基类，LangChain 内置无基类，三层独立组件通过 EventBus 松耦合无基类，三种独立机制：Prompt 组合函数 + Bash Hook 脚本 + 接口方法无基类，三条独立管道：Prompt sections 数组、Lifecycle 轮询函数、Hook Bash 脚本无基类，直接用 Callable 签名约束PlatformAdapter + EventHandler 双接口，Adapter 归一化 I/O，Handler 处理业务无统一基类，TrackedProvider 用 __getattr__ 透明代理，AgentLoop 用继承覆写无统一基类，Agent Hook 用 async Callable 协议，Channel Hook 用 BaseChannel 模板方法LangChain AgentMiddleware 泛型基类，声明 state_schema + toolsInteractionPlugin ABC，3 抽象 + 2 可选生命周期方法—DetectorPhase dataclass（label + run Callable + slow bool），无继承层次无显式基类，各阶段为 HybridRetriever 的私有方法无基类，LangChain 层用 @wrap_tool_call 装饰器，MCP 层用 @staticmethod无中间件基类，阶段为编排器私有方法双基类混合：ASGI 原生（ContentSizeLimit）+ Starlette BaseHTTPMiddleware + @app.middleware 函数式Starlette BaseHTTPMiddleware，dispatch + call_next 模式无统一基类，三层各自独立：EnvAPIRegistry / Role / BasePostProcessPluginHookHandler async trait + handle_sync 同步桥接无基类，纯函数 handler + PluginHookHandlerMap 类型映射，泛型约束 event/ctx/resultBaseObserver ABC 定义 get_status_table/is_healthy/has_errors 三方法契约无基类继承，ResponseBuffer 单类封装 annotate/ingest/flush 三阶段—无基类，纯 JSON 声明式配置 + 外部 shell command 子进程WorkflowStep dataclass，requires/produces 声明式依赖无基类，纯函数管道：buildVideoPrompt 输入 scene+profile+config 输出 string—四类 ABC 基类：StatLoggerBase/IOProcessor/Platform/CallableNodeMiddleware Protocol + ExtendedMiddleware 双层设计
钩子点5 类：before_agent/before_model/after_model/after_agent/wrap_tool_callEventBus subscribe 通配符模式（raw:*、signal:*）6 个：buildPrompt / postCreate / postLaunchSetup / setupWorkspaceHooks / PostToolUse / pollAllPostToolUse（Bash 命令后）+ postLaunchSetup（Agent 启动后）+ 状态转换事件6 种 Agent 生命周期钩子 + 工具调用中间件5 阶段：SessionStart / UserPromptSubmit / PostToolUse / Stop(2-phase) / afterFileEditchat() 后置追踪 + _process_message 前后置簿记Agent 层 pre_reasoning 1 个；Channel 层 4 个模板方法钩子before_agent / wrap_model_call / wrap_tool_call 三钩子，各有 async 版本7 个 InteractionPoint 枚举，覆盖 Planning/Research/Implementation—四阶段生命周期（generate/merge/noise_snapshot/persist）+ augmenter 串联7 个串行阶段 + Agency 模式分支，通过 config 开关控制LangChain before/after tool + MCP before/after interceptor 共 4 个挂载点无显式钩子，阶段间通过 console.print 输出统计receive 拦截（上传限制）、dispatch 拦截（断连/MIME）、全局 exception_handler请求前（上下文注入）+ 请求后（耗时日志 + 状态码分类）Role 管道 3 点（observe/think/act）+ Env 读写 2 点 + LLM 后处理 4 步17 种生命周期事件覆盖 Agent/LLM/Tool/Message/Session/Gateway24 种 hook 覆盖 6 大域：Agent/Message/Tool/Session/Subagent/GatewayEnqueueHookBase.on_enqueue 入队前 + DequeueHandlerBase.on_dequeue 出队后annotate（ID 注入）→ ingest（聚合/直通）→ flush（强制清空）三阶段链应用层 3 个（on_create/on_update/on_close）+ Git 层 5 个（pre-commit/post-merge/pre-push/post-checkout/prepare-commit-msg）9 种：PreToolUse/PostToolUse/SetUpEnvironment/Stop/SubagentStop/SessionStart/SessionEnd/UserPromptSubmit/Notificationbefore/after/on_error 三钩子 + LLM 层独立三钩子5 层语义层（Camera/Lighting/Subject/Mood/Style）+ Base Prompt + Speed + Continuity—四组 entry_points：general/platform/io_processor/stat_loggerbefore/after_node + before/after_pipeline + on_error 共 5 个
中间件数量11 层，_build_middlewares() 显式控制顺序3 层 × 多组件：5 个事件定义 + 5 条 YAML 规则 + 1 个行为3 层 Prompt + 1 个 Bash Hook + 1 个 postCreate + 16 个反应配置Prompt 3 层 + Lifecycle 4 级管道 + 7 个插件槽位Toolkit 中间件 + 6×2 种 Agent Hook（类级+实例级）3 Adapter + 7 Handler，共 10 个独立模块3 层：CostCapturing 子类 + TrackedProvider 包装 + AgentLoop 消息中间层Agent Hook 2 个（Bootstrap + MemoryCompaction）；Channel 钩子 4 个6 核心 + 3 条件（Memory/Skills/HITL），最多 9 层2 个默认插件：RequirementAnalysis + PlanReview—25+ 内置检测器 + 泛型插件动态注册，Python 语言 12 个 phase标准模式 7 阶段 + Agency 模式 4 轮迭代LangChain 层 2 个 + MCP 层 4 个 = 共 6 个中间件/拦截器7 个硬编码阶段（时间窗口/抓取/URL去重/AI评分/过滤+语义去重/富化/摘要）6 层：ContentSize + Sentry(条件) + CORS + MIME + boundary校验 + 查询归一化4 个：RequestContext / CORS / SecurityHeaders / RateLimitRole 管道固定 3 阶段，LLM 后处理固定 4 步，Env API 按装饰器动态注册3 内置 + 无限 shell hook（文件系统发现）24 种 hook 类型，每种可注册多个 handler，实际数量由插件决定4 个 Observer（Queue/VikingDB/VLM/Transaction）+ 2 个 Handler 基类4 组件：Buffer + Factory + Router + Service，非传统中间件链—无上限，每种 Hook 类型支持数组配置多个 Hook9 条命名管道，2-7 步骤/管道，共约 40 个步骤单镜头 5 层 + 组级 6 个横切关注点（引用/时间轴/对白/音频/风格/配额）—内置 2 个 general + 5 个 platform + 2 个 stat_logger8 个内置 + ContextManagementMiddleware 共 9 个
条件激活RunnableConfig.configurable 运行时配置驱动YAML where 子句 + matchEventType 通配符过滤buildPrompt 返回 null 跳过空组合；Hook 按 tool_name==Bash 过滤Prompt 层按 hasIssue/hasRules/hasUserPrompt 条件跳过运行时读取 _middlewares 列表，支持动态注册hooks.json matcher 字段 + handler 内 ensureWorkerRunning 前置守卫LangGraph conditional_edges 按 chosen_artifacts 是否为空路由BootstrapHook 文件标志一次性触发；MemoryCompaction 按 enable_memory_manager 条件注册参数非 None 时 append，None 时不加入管道should_trigger() 方法 + enabled 属性双重控制—_select_phases 按 slow/profile 双维度过滤，CI 模式跳过慢阶段和主观评审enable_agency_mode 配置切换双模，pseudocode 阶段按需激活MCP 拦截器按工具名条件注入（voiceover/search_media），非目标工具直接透传数据源按 config.enabled 条件激活，空列表提前退出Pydantic Settings 布尔开关：sentry_dsn/prometheus_enabled/mcp_server_enabledRATE_LIMIT_ENABLED 环境变量控制限流开关RoleReactMode 枚举切换 react 策略，_watch 过滤消息类型HookRequirements 资格检查（OS/bins/env）+ disabled 列表hasHooks() 快速判断跳过无注册 hook，插件内部自行条件过滤（如检查 channel）ObserverService 按依赖就绪状态决定是否创建 Observer，未就绪返回 unhealthy 占位事件枚举集合判断：_immediate_events 和 _buffered_events 两个 set—matcher 正则路由：通配符/精确/正则/MCP前缀四种模式，自动检测正则字符步骤级 capabilities 校验 + LLM 拦截器 where 过滤器findPresetToken 空值跳过 + translateToken skip 策略 + isValid 过滤无效值—VLLM_PLUGINS 环境变量白名单 + 模型 hf_config 驱动每个中间件独立环境变量开关 + 全局 MIDDLEWARE_PIPELINE_ENABLED
状态管理返回 dict 合并状态，返回 None 不修改纯函数不可变状态：Object.freeze + 环形缓冲区累加器key=value 元数据文件 + 原子 tmp+mv 更新Map<SessionId, SessionStatus> 内存状态 + key=value 文件持久化Hook 通过 deepcopy 传递参数，避免状态污染无状态 Hook 进程，所有状态通过 HTTP 委托给常驻 Worker ServiceClawWorkState dataclass 依赖注入 + WrapUpState TypedDict 管道状态Hook 实例持有自身状态；Channel 通过 _pending_content_by_session dict 管理去抖状态state_schema 声明 + PrivateStateAttr 隔离 + Annotated reducerDict[str, Any] context 链式传递，插件返回修改后的 context—ScanRuntime dataclass 封装全部上下文，findings 以 list[dict] 在阶段间传递PipelineContext 隐式传递（方法参数），迭代模式用 iteration_history 列表无实例状态，所有上下文通过 request.runtime.context 传递List[ContentItem] 原地修改传递，Pydantic 模型保证类型安全闭包累加器（receive_wrapper.received）+ Settings Service 全局单例ContextVar[dict] 存储请求上下文，跨线程通过 ContextThreadPoolExecutor 传播RoleContext 集中管理 state/todo/memory/news，Pydantic BaseModel 序列化无共享状态，每个 handler 独立 HookStats 原子计数器无共享状态，modifying hook 通过 merge 函数合并结果，void hook 无状态NamedQueue 线程锁保护 in_progress/processed/error_count 三计数器Dict[BufferKey, BufferEntry] 内存字典，BufferKey 四元组隔离—无状态：Hook 间通过环境变量和 stdin JSON 传递上下文，无共享内存dict[str, Any] 全局状态，步骤返回 dict 由框架合并无状态纯函数，每次调用独立计算，无共享可变状态—StatLoggerManager 扇出 + PerEngine/Aggregate 双模式patch dict 返回由引擎 update 合并，ReducerMiddleware 处理并行冲突
执行模型有序串行链，列表顺序即执行顺序同步 dispatch + try-catch 隔离，行为层支持 asyncPrompt 同步拼接；Hook 异步 Bash 子进程；轮询 30s 间隔Prompt 同步串行，Lifecycle 异步轮询 Promise.allSettled 并发洋葱模型（中间件）+ 顺序链（Hook）子进程模型：IDE spawn 独立进程执行 hook，进程退出码传递结果异步 async/await 全链路Agent Hook 串行 await；Channel 层 4 worker 并行消费，同 session key_lock 串行有序列表串行执行，框架按列表顺序调用钩子纯异步 async/await，asyncio.Future 等待用户响应—严格顺序执行，_run_phases 逐个调用 phase.run 并聚合结果标准模式同步串行，Agency 模式 LLM 驱动的迭代循环双层串行：LangChain 中间件链 → MCP 拦截器链 → MCP Server阶段间串行，阶段内 asyncio.gather 并发ASGI LIFO 栈 + asyncio.wait 竞赛（断连检测）Starlette 洋葱模型，CORS→SecurityHeaders→RateLimit→RequestContext→路由全异步 asyncio，Environment.run() 用 gather 并行执行所有 Role读事件 join_all 并行，写事件按 priority 串行，Block 短路双轨：void hook 并行 Promise.all，modifying hook 串行 for-of + merge拉模式：每次属性访问时 new Observer 读取最新状态，不缓存async emit 串行处理，ingest 内部同步聚合应用层异步 fire-and-forget，Git 层同步阻塞并行执行：同一事件的多个匹配 Hook 并行 spawn 子进程串行步骤 + WorkflowRunner Protocol 可插拔后端同步串行：5 层顺序拼接，组级 map+reduce 组装—加载期执行（general）+ 懒加载单例（platform）+ 请求级调用（stat）同步闭包包装，before 正序 / after_pipeline 逆序
同步热路径sync/async 双模，每个钩子有 a 前缀异步版本EventBus dispatch 和 RuleEngine processEvent 全同步buildPrompt 纯同步；PostToolUse Hook 5s 超时Prompt 组装纯同步，Hook 脚本 5s 超时Hook 支持同步和异步函数，通过 _execute_async_or_sync_func 统一全异步（async/await），通过 process.exit 退出码同步结果给 IDE—Agent Hook 全异步；Channel 的 enqueue 通过 call_soon_threadsafe 线程安全入队—无同步模式，全部 async（不适合热路径）——全同步执行，无异步阶段————ExtEnv 通过 is_coroutine_func 判断，支持 sync/async 双模调用dispatch_sync + handle_sync 默认 block_in_place 桥接tool_result_persist 和 before_message_write 强制同步，检测并拒绝 async handler同步 get_status_table() + 异步 get_status_table_async() 双模支持annotate + ingest 同步执行，persist 异步 await—PreToolUse/UserPromptSubmit 同步阻断：等待退出码决定是否继续—全同步，buildVideoPrompt 和 buildGroupPrompt 均为同步纯函数—record() 同步扇出，无异步开销—
错误隔离DanglingToolCallMiddleware 注入 synthetic error ToolMessage三级隔离：dispatch try-catch、rule try-catch、behavior try-catchpostCreate 失败回滚 workspace；postLaunchSetup 失败回滚 runtime+workspace+metadata每层 catch 静默，determineStatus 逐步降级不影响后续探测中间件和 Hook 异常会传播到调用者，无自动隔离isWorkerUnavailableError 二分类：infra 错误 exit 0 降级，code bug exit 2 上报每个 WrapUp 节点独立 try/except + _process_message 用 try/finally 保证 end_task每个 Hook 内部 try/except 吞异常只 log；Channel 层 consume_one 外层 catch 兜底—try/except continue，单插件失败不阻塞管道—hook_registry 捕获 5 种异常返回 None，augmenter 为纯函数不修改原数据每阶段 try-except 独立捕获，Agency 模式有 fallback 到标准模式handle_tool_errors 捕获异常转为含修复建议的 ToolMessage，不中断 Agent 循环return_exceptions=True 隔离数据源失败，AI 失败降级为 score=0全局 exception_handler 兜底 + 插件加载 try/except 隔离限流异常自动降级内存模式，认证异常返回 401/403 不影响其他中间件role_raise_decorator 捕获异常回滚 latest_observed_msg，消息可重新观察handler 错误 warn 日志不中断 + 熔断器自动禁用catchErrors 默认 true，单个 hook 失败不影响其他 hook 和主流程每个 Observer 独立 try-except，单组件故障不影响其他组件状态查询Router 返回 SideEffect 指令而非直接操作，编排层决定是否执行应用层 Hook 失败不阻塞主流程，Git Hook 失败阻止 Git 操作进程级隔离：Hook 以独立子进程执行，崩溃/超时不影响主进程strict=False 时拦截器异常仅 log 不阻断主流程每层独立：单层所有字段为空时该层静默跳过，不影响其他层—try/except 逐插件隔离，单插件失败不阻塞系统中间件异常 try/except 隔离，不影响主流程和其他中间件
数据传递ThreadState 共享状态 + runtime.context 传递 thread_idTracedEvent 不可变对象 + deepFreeze 递归冻结环境变量（AO_SESSION/AO_DATA_DIR）+ stdin JSON + metadata 文件Prompt 用 sections 数组，Lifecycle 用 OrchestratorEvent 结构体中间件通过 kwargs dict 传递，Hook 通过参数归一化传递—LangGraph 节点间通过 WrapUpState dict 传递；工具间通过 ClawWorkState 共享Agent Hook 通过 agent 实例直接操作 memory；Channel 钩子通过 request 对象传递元数据中间件返回 dict 或 Command，框架自动合并到 state——findings 为 list[dict] 扁平结构，_stamp_finding_context 统一后置注入 lang/zone—request.override(args=new_args) 不可变替换，拦截器间通过 args dict 传递List[ContentItem] 直接传递，无序列化开销scope dict 透传 + request.query_params 原地修改（flatten_query_string_lists）ContextVar + RequestContext.to_dict() 序列化，子线程 _data.copy() 深拷贝—HookPayload tagged enum 类型化载荷，ModifyPayload 替换 Value—回调注入：Handler.set_callbacks() 将 Queue 的计数方法注入 HandlerSaveItem dataclass 作为 Buffer→Persistence 的传输对象stdin JSON + 命令行参数（ID + event）双通道：环境变量（IFLOW_TOOL_NAME 等 10+ 变量）+ stdin JSONrequires/produces 声明式依赖链 + 注册时静态校验promptParts 数组累积，层间无显式上下文对象，通过闭包共享 scene/profile/config—SchedulerStats/IterationStats 结构化数据对象传递state dict 贯穿全链，中间件通过 _前缀字段传递元数据
可观测性—AsyncLocalStorage traceId/parentId 因果链 + DebugService 状态广播30+ EventType 事件系统 + Hook systemMessage 输出 + JSONL 会话日志OrchestratorEvent 含 id/type/priority/sessionId/timestamp/data通过 Hook 注入追踪逻辑，内置 Studio 消息转发 Hook—cost_line 追加到响应末尾 + JSONL 每任务综合记录logging.debug/info/error 分级日志，无结构化追踪logging.getLogger 记录摘要事件和 backend 操作——_run_phases 每阶段输出 [idx/total] label 进度到 stderr—ContextVar _MCP_LOG_SINK 推送 tool_start/tool_end/tool_progress 事件到 GUIrich.Console 每阶段输出条目数变化 + rich.progress 进度条OpenTelemetry FastAPIInstrumentor 自动插桩 + Prometheus 条件端口 + Sentry 条件集成ContextFilter 注入 trace_id 到每条日志，CustomLoggerRequestHandler 异步推送外部服务—HookStats 原子计数器（call/failure/latency）+ tracing 日志—tabulate 格式化表格 + ComponentStatus/SystemStatus 结构化数据双输出SaveItem 携带 item_id + agent_name + metadata 结构化追踪OpenTelemetry root span + stdout/stderr 作为 span eventsIFLOW_DEBUG=1 启用详细日志，PostToolUse 可记录执行统计LLM 层拦截器提供 request_id/trace_id/usage/latency——Prometheus 默认保底 + 自定义 StatLogger 插件扩展TracingMiddleware ContextVar + TaskLogMiddleware 步骤级耗时
去抖队列MemoryMiddleware 通过 threading.Timer 30s 去抖批量更新记忆滑动窗口累加器替代去抖：threshold+window 聚合高频事件—————双层去抖：无文本内容缓冲 + 时间窗口 asyncio.Task 延迟 flush—————————————————————
懒初始化策略Sandbox/ThreadData 支持 lazy_init 参数延迟资源获取Awilix DI 容器 lazy resolve + 显式 init() 两阶段初始化—————MemoryManager 按 enable 标志条件创建；Channel 按 available_channels 配置按需实例化Backend 工厂模式：接受实例或 callable，运行时延迟创建——hook_registry 首次 get_lang_hook 时 importlib 惰性导入语言包—LLM 池 _get_llm 按 (model_name, streaming) 键懒创建并缓存—receive 时动态读取 max_file_size_upload，支持运行时修改无需重启Redis 客户端和 PostgreSQL 连接池均首次使用时创建，失败静默降级———————LLM 客户端按 profile 懒创建并缓存——__getattr__ 模块级懒加载平台单例—
环形错误缓冲—累加器 counts 环形缓冲区，advanceSlots 自动清零过期槽位——————————————————QueueError 列表截断到 MAX_ERRORS=100，防止内存泄漏————————
双向序列化—TracedEvent deepFreeze 确保不可变，YAML 规则双向：文件↔ParsedRule————————————————HookPayload serde tagged enum 支持 JSON 序列化/反序列化往返——Factory.from_conversation_item 支持持久化记录反向重建 BaseResponse———————
声明式规则引擎—YAML DSL 定义 trigger/accumulator/signal 三段式规则———————————————————————————
TypeScript逃生舱—TypeScriptRule 接口允许复杂逻辑绕过 YAML 限制———————————————————————————
信号过滤转发—ReflexManager.shouldForwardToConscious 按信号类型过滤———————————————————————————
行为竞选机制—score 评分 + cooldown 冷却 + mode 过滤的行为选择———————————————————————————
交互桥接ClarificationMiddleware 通过 Command(goto=END) 中断等待用户—无直接交互桥接，通过 Lifecycle Manager 的 needs_input 状态间接检测notifyHuman 按 priority 路由到 desktop/slack/webhook notifier—stderr 劫持 + userMessageHandler 通过 stderr 向用户展示上下文———WorkflowPluginIntegration 通过 WebSocket + asyncio.Future 连接前端———————Environment.publish_message 按 send_to 路由，Role.put_message 放入私有 buffer———————————
装饰器包装——无装饰器，采用接口方法（postCreate/postLaunchSetup）的可选实现模式——hookCommand 函数包装 adapter→handler 管道，stderr 劫持作为 AOP 切面__class__ 运行时类变更 + TrackedProvider 组合包装，不修改上游源码—wrap_model_call 接收 handler 函数，形成洋葱模型create_plugin_enabled_wrapper 高阶函数，零修改包装已有函数———@wrap_tool_call 装饰器实现 before/after 语义，handler 参数传递下一层——认证用 FastAPI Depends 依赖注入而非中间件，require_scope() 工厂模式@mark_as_readable/@mark_as_writeable 注册到全局 Registry，零侵入无装饰器，通过 dispatch 调用点显式集成—————LLMClientWrapper __getattr__ 代理 + _invoke 统一拦截———wrap_node 闭包而非 Python 装饰器，适配 LangGraph add_node API
通知路由——四级优先级路由（urgent/action/warning/info）→ 多 notifier 并行推送4 级优先级（urgent/action/warning/info）→ notifier 列表映射——————————————读事件并行通知所有 handler，无按严重度分发—CLI Typer 命令组 + FastAPI /api/v1/observer/* 双通道暴露NotifyResponseEvent.MESSAGE 作为 immediate 事件直通持久化—Notification Hook + matcher 正则匹配通知内容，退出码 2 旁路显示—————
反应升级——双维度：retries 次数 + escalateAfter 时间窗口，超限自动升级为人工通知retries 次数 + escalateAfter 时间窗口双维度升级到人工通知—————————————————————————
超时保护——Hook 脚本 5s 超时；Git 命令 30s 超时；轮询重入保护Hook 脚本 5000ms timeout，session 探测 2s enrichment timeout——————————httpx.AsyncClient(timeout=30.0) 全局 HTTP 超时asyncio.wait + 100ms 轮询断连检测，返回 499 状态码RequestContextMiddleware 记录请求耗时但无硬超时，依赖 uvicorn/gunicorn 层面超时—ShellHookHandler tokio::time::timeout 可配置超时—TransactionObserver.get_hanging_transactions(threshold=300s) 被动检测—10s 超时 + Unix 进程组终止（kill -pid）+ Windows 单进程终止每个 Hook 独立 timeout 配置（秒级），超时自动终止不中断主流程—————
外部管理器集成——无外部 Hook 管理器冲突处理，直接写入 .claude/settings.json无外部 Hook 管理器，直接写入 .claude/settings.json——————————————HOOK.md 文件系统发现 + TOML frontmatter 元数据—Observer 持有 Manager 引用（组合模式），不继承不侵入—自动检测 lefthook/husky/pre-commit，链式调用 .old hook无外部 Hook 管理器冲突检测，纯 iflow 自有配置———外部 entry_points 插件优先级高于内置插件—
版本同步——Hook 幂等注册：检测 metadata-updater.sh 存在则更新命令，不重复添加Hook 脚本每次 postLaunchSetup 重写，自动保持最新——————————————————薄垫片委托模式（exec tool hooks run），升级 CLI 自动更新 Hook 逻辑无版本检测机制，Hook 配置随 settings.json 版本控制PipelineRevision 不可变修订历史 + revision_token 全局指纹————
双层分离————Toolkit 中间件处理工具调用，Agent Hook 处理生命周期————————————————————————
元类自动包装————通过 _AgentMeta 在类定义时自动为核心方法注入 Hook————————————————————————
统一流式接口————所有工具返回 AsyncGenerator，非流式自动包装————————————————————————
类级+实例级 Hook————类级 Hook 全局生效，实例级 Hook 仅当前实例————————————————————————
OrderedDict 存储————Hook 按注册顺序执行，执行顺序可预测————————————————————————
参数归一化————*args/**kwargs 统一为 kwargs dict，简化 Hook 处理————————————————————————
流式后处理————postprocess_func 应用于每个 chunk，支持流式修改————————————————————————
中断处理————_async_generator_wrapper 捕获 CancelledError 并注入中断消息————————————————————————
成本预算控制——————0.6 评估阈值悬崖 + 四渠道分类统计（llm/search/ocr/other）—SummarizationMiddleware 基于 fraction/tokens/messages 三种阈值触发压缩———max_total_lines 行数预算 + budget_usage_pct 追踪———————————————TokenBudgetMiddleware 按节点权重分配预算，超 80% 触发压缩
悬挂工具调用修复————————PatchToolCallsMiddleware 在 before_agent 扫描并补丁 cancelled ToolMessage————————————————————
并发限流SubagentLimitMiddleware after_model 截断超限 task 调用 [2,4]—————————————Reddit 用 asyncio.Semaphore(5) 限流，HN 无显式限流ContentSizeLimitMiddleware 按请求累计字节数限流，非全局限流Redis Sorted Set 滑动窗口 + 进程内 defaultdict(list) 内存回退————————————
副作用注册模式———————————语言包 __init__.py 导入时执行 register_lang_hooks 副作用注册钩子—————————————————
置信度驱动停止————————————LLM 每轮评估 confidence(0-100)，达阈值即停————————————————
自适应参数————————————根据 query_complexity 动态调整 iterations/threshold/budget 三参数————————————————
加权合并策略————————————三路搜索结果按 YAML 配置权重累加，BM25 先归一化————————————————
渐进式过滤——————————————7 阶段逐步缩减数据量，富化仅处理高分条目节省 AI 成本——————————————
双层去重——————————————URL 归一化去重（AI 前）+ Jaccard+Tag 语义去重（AI 后）——————————————
媒介类型翻译—————————————————————————4 种媒介（cinematic/animation/stop-motion/graphic）的字段级翻译表，三级降级策略———
摄影档案回退—————————————————————————13 个字段逐一 scene.field || cinProfile?.default 回退，6 维档案覆盖灯光/焦点/器材/氛围/速度/角度———
Prompt层级优先级—————————————————————————组级三级：手动编辑 > AI校准 > 自动拼接；单镜头五层：Camera > Lighting > Subject > Mood > Style———
配额守卫—————————————————————————SEEDANCE_LIMITS 硬编码（≤9图/≤3视频/≤3音频/≤12总/≤5000字符），引用收集时前置校验———

最佳实践

1.中间件顺序有依赖关系：ThreadData 必须最先（创建目录），ClarificationMiddleware 必须最后（拦截澄清）

2.条件激活减少开销：不需要的中间件通过 RunnableConfig 动态禁用，避免无谓执行

3.状态合并而非直接修改：中间件返回 dict 由框架合并，避免并发修改冲突

4.同步/异步双模：支持同步和异步调用场景，异步版本用 a 前缀（abefore_model）

5.横切关注点必须独立可测：每个中间件可以独立单元测试，不依赖其他中间件

6.纯函数状态管理：累加器和匹配器全部纯函数 + Object.freeze，零副作用便于测试

7.三级错误隔离：EventBus dispatch、RuleEngine rule、ReflexRuntime behavior 各层独立 try-catch

8.YAML 规则 + TypeScript 逃生舱：声明式覆盖 80% 场景，编程式处理复杂逻辑

9.信号语义过滤：反射层过滤高频低语义信号（entity_attention），只让决策相关信号到达 LLM

10.Prompt 组合返回 null 而非空字符串：裸启动不注入空 prompt，保持 Agent 默认行为

11.Hook 注册幂等性：写入前扫描已有配置，存在则更新不重复添加

12.元数据原子更新：tmp 文件 + mv 替换，防止并发写入导致文件损坏

13.Prompt 管道返回 null 表示无内容：向后兼容裸启动场景

14.反应执行抑制直接通知：避免 reaction 和 notification 双重触发

15.状态转换时清除旧反应计数器：确保新状态的反应从零开始

16.状态转换时重置反应追踪器：避免重试计数跨状态累积导致误升级

17.插件探测失败保留当前状态：catch 中返回 session.status 而非默认值，防止状态抖动

18.PostToolUse Hook 原子写入：mv temp_file 保证元数据文件一致性

19.并发轮询用 Promise.allSettled：单个 session 探测失败不阻塞其他 session

20.反应配置支持项目级 override：全局默认 + 项目特化，用 spread 合并

21.元类自动包装：通过元类在类定义时自动为核心方法注入 Hook，子类无需手动装饰器

22.统一流式接口：所有工具返回 AsyncGenerator，非流式工具自动包装，简化中间件实现

23.双层分离：Toolkit 中间件处理工具调用，Agent Hook 处理生命周期，关注点清晰分离

24.类级+实例级 Hook：类级 Hook 全局生效（如监控），实例级 Hook 个性化定制（如调试）

25.参数归一化：将 *args/**kwargs 统一为 kwargs dict，简化 Hook 的参数处理逻辑

26.OrderedDict 存储：Hook 按注册顺序执行，执行顺序可预测，便于调试

27.未知事件返回 no-op handler 而非抛异常：宿主 IDE 新增事件不会导致插件崩溃

28.错误二分类（infra vs code bug）决定退出码：网络抖动静默降级，代码 bug 上报开发者

29.stderr 劫持防止宿主 IDE 误判：Hook 期间所有诊断走日志文件，stderr 保持干净

30.自定界 JSON 解析替代 EOF 等待：每个 chunk 尝试 parse，成功即 resolve，兼容不关闭 stdin 的宿主

31.Provider 包装必须在 super().__init__() 之后：确保 self.provider 已被父类初始化

32.try/finally 保证 end_task：即使处理异常也能正确关闭任务成本记录

33.优先使用上游报告的 cost 字段：OpenRouter 等中间商的真实费用比本地估算更准确

34.工厂函数封装工作流创建：create_wrapup_workflow 隐藏初始化细节，便于测试替换

35.Hook 即 Callable 最小协议：async __call__(agent, kwargs) 比继承基类更灵活，任何 async 函数都能当 Hook

36.一次性 Hook 用文件标志而非内存标志：进程重启后仍能记住已触发状态

37.Channel 去抖前置于业务钩子：先去抖再调 _before_consume_process，减少无效钩子调用

38.子代理独立构建中间件栈：每个子代理获得独立的 Summarization/Filesystem 实例，避免共享状态冲突

39.工具注入通过 self.tools 属性：中间件在 __init__ 中创建工具，框架自动收集并注入 agent

40.大结果驱逐排除内置工具：ls/glob/grep/read_file 等自带截断的工具不参与驱逐，避免二次截断

41.懒加载避免循环导入：get_default_registry(auto_register) 参数控制是否立即导入插件模块

42.插件内资源懒初始化：RequirementAnalysisPlugin 的 _get_agent() 延迟到首次触发时才创建 Agent 实例

43.装饰器模式零侵入：create_plugin_enabled_wrapper 包装已有函数，不修改原始代码即可注入 hook

44.懒初始化减少冷启动开销：Sandbox 和 ThreadData 默认 lazy_init=True，首次使用时才分配资源

45.wrap_tool_call 拦截优于工具内判断：澄清逻辑在中间件层拦截而非工具实现内部处理，保持工具纯净

46.去抖队列替代同步写入：MemoryMiddleware 投递到 Timer 去抖队列，避免阻塞 Agent 主流程

47.after_model 硬截断比 prompt 限制更可靠：SubagentLimitMiddleware 直接截断 tool_calls 而非依赖 LLM 遵守 prompt 指令

48.泛型状态切片声明：每个中间件用 AgentMiddleware[S] 声明所需字段，编译期发现缺失

49.懒初始化默认开启：ThreadData 和 Sandbox 默认 lazy_init=True，短对话零资源开销

50.wrap_tool_call 实现流程中断：ClarificationMiddleware 通过 Command(goto=END) 优雅中断 Agent 循环

51.Orchestrator 用 Callable 字段而非虚方法：测试时直接替换函数，无需子类化

52.检测器元数据用 frozen dataclass：不可变保证注册后不被意外修改

53.语言钩子惰性加载捕获宽异常谱：ImportError 到 OSError 五种异常确保任何导入失败都优雅降级

54.多层安全过滤兜底：每个检索阶段都检查 repo_filter，最终用 _final_repo_filter 兜底防止数据泄漏

55.BM25 分数归一化后再加权：不同搜索引擎的分数量纲不同，必须先归一化到 0-1 再乘以权重

56.迭代模式跳过查询预处理：Agency 模式下 IterativeAgent 自行处理查询增强，避免 QueryProcessor 的冗余 LLM 调用

57.文件级多样化惩罚：同一文件的后续结果施加衰减因子，避免结果过度集中在单个文件

58.静态方法拦截器无实例状态：所有上下文通过 request.runtime.context 传递，避免拦截器间状态耦合

59.args.setdefault 保护已有参数：条件注入时不覆盖 LLM 已设置的参数值

60.ContextVar 日志通道解耦 GUI/CLI：不同前端通过 set_mcp_log_sink 注入各自的日志回调

61.空列表提前退出：每阶段检查输入为空则跳过后续所有阶段，避免无意义计算

62.AI 失败降级不丢弃：分析异常时赋 score=0 保留条目，由后续阈值自然过滤

63.渐进式过滤节省成本：URL 去重在 AI 评分前执行，语义去重在评分后执行，富化仅处理高分条目

64.ASGI 原生中间件适合 receive/send 拦截场景，BaseHTTPMiddleware 适合 request/response 拦截

65.插件路由注册必须通过代理包装器，收集已有路由集合后逐一冲突检测

66.配置驱动的中间件激活应延迟 import，未启用时零开销（如 Sentry SDK）

67.断连检测用 asyncio.wait 竞赛模式，轮询间隔 100ms 平衡灵敏度与 CPU 开销

68.限流先于认证注册：防止未认证请求通过暴力破解消耗认证数据库资源

69.Redis 限流用 Pipeline 原子操作：ZREMRANGEBYSCORE+ZCARD+ZADD+EXPIRE 四命令一次往返

70.ContextThreadPoolExecutor 深拷贝 _data：子线程修改不影响主线程上下文

71.认证用依赖注入而非中间件：不同路由需要不同 scope 时，Depends 比全局中间件更灵活

72.trace_id 多 header 优先级链：兼容 Google Cloud Trace（g-trace-id）和自定义 header

73.装饰器注册零侵入：子类方法加 @mark_as_readable 即自动注册，无需显式调用 register()

74.管道阶段固定顺序：observe→think→act 三阶段不可跳过，保证消息处理一致性

75.异常回滚消息：role_raise_decorator 在异常时删除 latest_observed_msg，使消息可被重新观察

76.sync/async 双模分发：ExtEnv 通过 is_coroutine_func 判断后选择 await 或直接调用

77.读写事件静态分类：编译期 is_read_only() 确定调度策略，避免运行时判断开销

78.熔断器用原子操作实现：AtomicU64/AtomicBool 无锁统计，不引入 Mutex 竞争

79.Shell Hook 退出码语义固定：0=放行 1=拦截 其他=错误，脚本作者无需学习复杂协议

80.Dry-run 模式：新 hook 上线前可在生产环境验证行为而不影响主流程

81.hasHooks 前置检查：触发 hook 前先检查是否有注册 handler，避免无谓的事件对象构造开销

82.Promise 检测守卫：同步 hook 检测 handler 返回值是否为 Promise，防止异步污染同步热路径

83.类型映射而非运行时校验：用 PluginHookHandlerMap 泛型在编译期保证 hook 签名正确

84.Observer 每次查询时新建实例：避免缓存过期状态，始终读取最新数据

85.回调注入解耦 Handler 与 Queue：Handler 通过 report_success/error 回调更新计数，不直接操作 Queue 内部状态

86.环形缓冲区限制错误记录：MAX_ERRORS=100 截断防止内存泄漏，保留最近错误供诊断

87.组合优于继承：Observer 持有 Manager 引用而非继承，职责清晰不侵入业务逻辑

88.snapshot 而非 drain：每次 ingest 返回完整聚合内容做 upsert，不清空 buffer，支持增量更新

89.REASONING 事件信任调用方 item_id：编排层预设的关联 ID 优先于 buffer 分配的段落 ID

90.BufferKey 四元组隔离：conversation_id + thread_id + task_id + event 确保多 Agent 多事件类型互不干扰

91.Factory 双向转换：构造方法和 from_conversation_item 共用同一套类型系统，消除序列化/反序列化不一致

92.薄垫片优于内联脚本：Git Hook 仅包含委托调用，实际逻辑在 CLI 二进制中，升级无需重装 Hook

93.链式集成优于覆盖：检测到外部管理器时自动 --chain 模式，保留用户现有工作流

94.进程组终止必须用负 PID：Unix 下 kill(-pid) 确保子进程也被终止，避免僵尸进程

95.应用层 Hook 必须异步：fire-and-forget 模式确保 Hook 失败不阻塞主流程，保证系统可用性

96.Git Hook 必须同步：pre-commit/pre-push 需要阻塞 Git 操作，通过退出码控制是否继续

97.退出码语义按 Hook 类型分层：阻断型 Hook（PreToolUse/UserPromptSubmit）非零阻断，旁路型 Hook（Notification）退出码 2 仅显示 stderr，其他 Hook 退出码不影响主流程

98.matcher 无效正则自动降级：正则编译失败时回退到精确匹配，避免配置错误导致 Hook 完全失效

99.环境变量 + stdin 双通道传参：简单元数据用环境变量（跨语言兼容），复杂结构化数据用 stdin JSON

100.拦截器用 immutable tuple 存储，注册时创建新 tuple 实现无锁读取

101.管道变更采用 copy-on-write：复制步骤列表 → 执行变更 → 校验 → 追加新 revision

102.WorkflowInterceptorHandle 支持一次性 dispose，防止重复移除

103.revision_token 生成全局版本指纹（name:vN|...），可用于缓存失效判断

104.纯函数管道无副作用：prompt builder 输入不可变数据输出字符串，可独立测试和复用

105.翻译而非过滤：跨媒介适配时将物理摄影词汇翻译为等效表达，保留语义完整性

106.三级降级策略：字段级 skip → 预设级 override → 默认直通，兼容未来新增预设

107.entry_points 插件必须设计为可多次加载（多进程 fork 场景），用全局标志保证幂等

108.外部插件优先级高于内置插件，但同类外部插件最多只能激活一个

109.Prometheus 等默认实现作为保底，即使无自定义插件也有基础可观测性

110.插件基类用 ABC 强制接口契约，加载时 issubclass 检查而非运行时 duck typing

111.Protocol 协议优于抽象基类：用 @runtime_checkable Protocol 定义中间件接口，不强制继承

112.on_error 首胜策略：多个降级中间件中第一个返回非 None 的生效，避免冲突

113.环境变量双层开关：全局开关 + 每个中间件独立开关，生产环境可逐个禁用

114.闭包包装而非装饰器：wrap_node 返回闭包适配框架 API，不侵入节点定义