双抽象：Builder 与 Pipeline

第一层抽象是面向"声明"的 Builder：使用者通过链式 API 描述角色、工具白/黑名单、记忆后端、嵌入模型等参数；Builder 不直接执行业务逻辑，只把声明物冻结成不可变的执行上下文（Manifest）。资料来源：src/geny_executor/core/builder.py:1-120

第二层抽象是面向"运行"的 Pipeline：接收 Builder 产出的 Manifest，按固定顺序驱动 21 个 Stage，并对异步 I/O、临界区、错误隔离负责。Pipeline 必须是事件循环友好的——正如 v2.48.2 修复的 LoopAgnosticLock.__aenter__ 死锁所示，所有跨 await 的临界区都被设计为 fast-try + 工作线程等待，避免阻塞 loop 线程。资料来源：src/geny_executor/core/pipeline.py:40-180

两条主线的边界刻意清晰：Builder 不持有任何 I/O 句柄，Pipeline 不接受运行时配置改写。这让同一份 Builder 输出可以被多条 Pipeline 反复回放，方便回归与重放测试。

21 阶段管道的四组划分

Stage 是最小执行单元，输入 StageContext、产出一个增量字段并向下传递。21 个阶段按职责分为四组：

入口组的 argv 处理遵循 POSIX 规范——v2.45.1 修复的 -- 分隔符正是为了让变长 --allowedTools 不再吞掉位置 prompt 参数；非流式带图像调用则走 stream-json wire（v2.45.0）。资料来源：src/geny_executor/core/pipeline.py:60-95、src/geny_executor/core/manifest_factory.py:30-110

上下文组的关键是 hybrid 检索（v2.47.0 引入的 Qdrant 向量后端 + 关键词），由 Stage 7 统一调度，Stage 8 把它与事实账本（v2.46.0）合并注入。资料来源：src/geny_executor/core/presets.py:50-140

Stage、Presets 与 ManifestFactory 的协作

每个 Stage 的执行细节由 presets.py 决定。Presets 是一组不可变配置快照——角色模板、向量集合名、嵌入维度上限、CLI 路径等——通过依赖注入进入 Stage，避免运行时重新加载。资料来源：src/geny_executor/core/stage.py:20-160

例如嵌入阶段的 8192 字节上限（v2.48.1）就是 Preset 中的硬约束，由推理组的 Stage 在调用 OpenAI 客户端前做 UTF-8 边界截断。manifest_factory.py 则在每次执行开始时为 Stage 链生产唯一清单，决定哪些可选能力（如 qdrant extra）会被装配进当次管道。资料来源：src/geny_executor/core/presets.py:90-130、src/geny_executor/core/manifest_factory.py:60-140

持久化组与回滚闭环

后 8 个阶段处理副作用。Stage 14–16 负责记忆与向量的双写：文件提供者以 facts_json 单字段写入（v2.46.1），向量库通过可选 VectorHandle 协议分块索引，并由 fetch_document(ref) 重组整篇文档（v2.48.0）。Stage 17–21 处理结构化回执、失败回滚、锁释放与审计日志。任何阶段抛出异常都会被 Pipeline 捕获并按预设策略执行幂等回滚——remove() 不再触发维度校验（v2.47.1），使得回滚可以清理切换嵌入模型后的遗留集合。资料来源：src/geny_executor/core/pipeline.py:200-340

flowchart LR
  A[Builder<br/>声明侧] -->|不可变 Manifest| B[Pipeline<br/>运行侧]
  B --> G1[1-4 入口]
  G1 --> G2[5-8 上下文]
  G2 --> G3[9-13 推理]
  G3 --> G4[14-21 持久化]
  G4 --> R[回执 / 审计]
  G1 -.读取.-> P[presets.py]
  G2 -.读取.-> P
  G3 -.读取.-> P
  G4 -.读取.-> P
  P --> M[manifest_factory.py]
  M --> B

小结

• Builder 与 Pipeline 是不可混淆的两层抽象，分别负责声明与执行。
• 21 阶段按入口 / 上下文 / 推理 / 持久化四组划分，覆盖 CLI 装配到向量索引的全部副作用。
• Stage 是最小执行单元，Presets 提供不可变配置，ManifestFactory 产出每次执行的清单——三者与 Builder/Pipeline 共同构成可观测、可回放、可回归的执行内核。

llm_client 子包是 geny-executor 与外部大模型服务（Anthropic Claude、OpenAI、Google Gemini、本地 vLLM 等）交互的统一边界。其设计目标是把不同提供者的鉴权、消息线协议、流式语义、嵌入接口与多模态载荷差异收敛到同一组高层调用之下，让上层 agent、记忆维护与向量写入路径只面对稳定形状的请求/响应对象，而不被任一提供者的私有协议污染。

1. 抽象边界与统一客户端形状

llm_client 子包对外暴露的不是「某一个 SDK 的再封装」，而是一组「统一消息 → 提供者原生负载 → 统一响应」的转换流水线。调用方通常传入标准化的 messages、tools、system、temperature 等字段，由各提供者适配器负责把这种统一形状翻译成对应的 HTTP/CLI 形态。

• registry.py 维护提供者名称到具体适配器类的映射，是唯一允许在运行时引入新提供者的注册点。资料来源：src/geny_executor/llm_client/registry.py:1-80
• credentials.py 集中管理 API Key、Bearer、project/region 等凭据的解析顺序（环境变量 > 配置文件 > 默认值），并保证凭据对象不会泄漏到日志或异常消息中。资料来源：src/geny_executor/llm_client/credentials.py:20-120

统一抽象同时承担运行时安全职责：所有调用在事件循环线程中必须非阻塞（见 v2.48.2 的 LoopAgnosticLock 修复），任何需要跨 await 的同步获取都被改写为「快速尝试 + 工作线程等待」的形态，避免一次嵌入 HTTP 调用把整个后端冻住。资料来源：src/geny_executor/llm_client/registry.py:80-140

2. 各提供者适配要点

anthropic.py、openai.py、google.py、vllm.py 四个文件分别承担不同提供者的协议细节，但保持同样的内部结构（构造 → 鉴权 → 编码 → 调用 → 解码 → 重试）。

• anthropic.py 围绕 Claude Code CLI 的两条线路展开：非流式 create_message 在携带图像块时必须走 stream-json 线路，因为位置参数 --print 是纯文本信道，无法投递图片；多轮 stream stdin 则需要保留当前轮的 image blocks，避免被压平成 [image attachment]。CLI argv 中 --allowedTools/--disallowedTools 之后必须用 POSIX -- 终结选项，否则提示词会被解析为工具规则（v2.45.0、v2.45.1 修复点）。资料来源：src/geny_executor/llm_client/anthropic.py:60-220
• openai.py 同时实现 Chat Completions 与 Embeddings。嵌入客户端在 v2.48.1 中加入「输入字节预算」护栏：每条输入 ≤ 8192 字节（等价于 token 预算上限），超出部分按 UTF-8 边界截断而非报错，从而避免单条过长文本触发 400 并楔住整条嵌入写入路径。资料来源：src/geny_executor/llm_client/openai.py:140-260
• google.py 处理 Gemini 的 generateContent / streamGenerateContent 双形态，重点在工具调用结果的多轮拼装与安全设置（safety settings）的透传。资料来源：src/geny_executor/llm_client/google.py:40-160
• vllm.py 面向本地 OpenAI 兼容端点，强调 base URL 探测、/v1/models 自描述以及流式 chunk 的 SSE 解析一致性，是离线/私有化部署场景的主要入口。资料来源：src/geny_executor/llm_client/vllm.py:30-140

3. 流式、重试与并发安全

抽象层对调用方承诺三条不变量，无论底层走哪种提供者：

1. 流式语义统一：所有提供者都以「增量文本 + 工具调用增量 + 最终 usage」三段式向外吐帧，差异被吸收在解码器内。
2. 重试边界受控：429/5xx 在提供者内部退避重试，但 token 预算、图像载荷等结构性错误立即抛出，避免被吞掉。
3. 循环不阻塞：await client.complete(...) 在事件循环线程内不持有任何同步锁；并发由 LoopAgnosticLock 的非阻塞快速路径仲裁（v2.48.2 修复点）。

这三条不变量共同保证上层记忆维护、向量写入与 CLI 流不会因为一个提供者变慢而级联阻塞。资料来源：src/geny_executor/llm_client/registry.py:140-210

4. 与上层系统的契约

llm_client 子包不孤立存在，它与 memory（Fact Ledger、schema-bound memory）、vector_store（QdrantVectorStore）、CLI argv 解析之间存在明确的上下游契约：调用方传入的 system 注入、tools schema 与图像附件必须原样保留到提供者侧；而调用方接收到的 usage、tool_calls 与 finish_reason 必须是「可重放」的统一形状，以便上层做 budget 控制、回放与审计。资料来源：src/geny_executor/llm_client/credentials.py:120-180

任何新增提供者都应仅修改 registry.py 的注册表与一个对应 *_provider.py 文件，不应改写上层调用代码——这是该抽象层存在的核心目的。

概述

geny-executor 的记忆子系统负责在多次会话/轮次之间持久化、维护并检索"知识"，为 LLM 推理提供上下文窗口。子系统由三条主干组成：

1. FileMemoryProvider —— 基于本地文件的笔记/索引/汇总层，承载 <root>/_index.json、<cat>/_index.json、<root>/_summary.json 以及被固定注入的 __facts__.md。
2. Fact Ledger —— 一份"始终注入、可检索"的事实账本，物理上落在 __facts__.md 笔记里，以单条 facts_json 标量形式持久化。
3. QdrantVectorStore —— 可选 [qdrant] 扩展提供的向量后端，实现统一的 VectorHandle 协议。

三者通过 composite/provider.py 中的组合 Provider 聚合，对应 v2.46.0 提出的"LLM 判定 / Schema 约束 / 代码落库"三段式结构化记忆维护。

资料来源：src/geny_executor/memory/composite/provider.py:1-200

锁与并发：LoopAgnosticLock

记忆路径上的所有写操作都必须串行化，否则在并发 async 路径下会出现"读到一半再被覆盖"的不一致。_locks.py 提供的 LoopAgnosticLock 专门解决如下死锁场景：

• 协程 A 持有锁并跨越 await（例如 vector_store.index(...) 等待 embedding HTTP 响应）。
• 协程 B 在事件循环线程上再次 __aenter__。旧实现里直接做同步 acquire，整条循环被冻结 —— 整后端失联。

v2.48.2 的修复把 acquire 改为对事件循环非阻塞：先做一次快速 try，竞争时切换到工作线程等待。读端不会饥饿，写端依然互斥；并新增了"vector_store.index 在锁内 await 嵌入 HTTP"的回归测试。

资料来源：src/geny_executor/memory/_locks.py:1-200、[CHANGELOG [2.48.2]]()

Fact Ledger：__facts__.md + facts_json

Fact Ledger 是子系统的"事实骨干"：

• 存储格式：单条 facts_json 字段（一个 JSON 标量），不再使用嵌套 YAML 行。这避免了 v2.46.0 时把列表写进前页后被文件写入器二次 stringify、next pass 静默清空的事故（v2.46.1 修复）。
• 写入策略：LLM 输出"事实 diff"，代码按 diff 应用/合并到 facts_json，再写回 note。
• 加载策略：启动时 Loader 既识别新版的 facts_json，也兼容 v2.46.0 的旧嵌套行（向后恢复）。
• 测试：FileMemoryProvider 真实落盘-读回 round-trip，不再依赖 mock（4506 tests）。

配合 Rollup v2，"滚动摘要/evergreen"也以 schema-bound JSON 形式由代码渲染，LLM 只能产出符合 schema 的内容，渲染端完全在代码侧 —— 把"自由文本记忆"收窄为"可校验结构"。

资料来源：src/geny_executor/memory/facts.py:1-200、src/geny_executor/memory/rollup.py:1-200、[CHANGELOG [2.46.0]]()、[CHANGELOG [2.46.1]]()

向量后端：QdrantVectorStore

向量能力是 [qdrant] 扩展，按需启用。QdrantVectorStore 实现统一的 VectorHandle 协议，对外暴露以下原语：

v2.48.1 给 OpenAI embedding 客户端加了 ≤8192 字节的输入预算护栏：超长输入在 UTF-8 边界截断，避免长文本直接 400 把整条嵌入路径卡死。

资料来源：src/geny_executor/memory/vector/qdrant_store.py:1-300、src/geny_executor/memory/retriever.py:1-200、[CHANGELOG [2.47.0]]()、[CHANGELOG [2.47.1]]()、[CHANGELOG [2.48.0]]()、[CHANGELOG [2.48.1]]()

端到端检索与写回

flowchart LR
    A[用户查询] --> B[composite/provider]
    B --> C[Fact Ledger<br/>__facts__.md · facts_json]
    B --> D[Rollup v2<br/>schema-bound JSON]
    B --> E[FileMemoryProvider<br/>_index / _summary]
    B --> F[QdrantVectorStore<br/>vector + keyword]
    C --> G[上下文拼装]
    D --> G
    E --> G
    F --> G
    G --> H[LLM]
    H --> I[事实 diff]
    I --> J[LoopAgnosticLock]
    J --> K[持久化<br/>facts / rollup / vector]

组合 Provider 把"事实 / 摘要 / 笔记 / 向量"四条通道拼成一个上下文窗口；写回侧统一走 LoopAgnosticLock，因此即使写路径里嵌了 await vector_store.index(...)，也不会再把事件循环锁死（v2.48.2 之前的真实事故）。

资料来源：src/geny_executor/memory/composite/provider.py:40-200、src/geny_executor/memory/retriever.py:30-200

已知约束与运维提示

• 切换 embedding 模型后清理旧向量：直接使用 QdrantVectorStore.remove(filter)，无需担心维度不匹配；缺失 collection 是 no-op（v2.47.1）。
• 超长输入：OpenAIEmbeddingClient 会在 UTF-8 边界截断到 8192 字节，长文档请先分块再嵌入，避免被截断后语义偏移（v2.48.1）。
• 整篇文档读取：上层工具请用 fetch_document(ref)，不要自行按 chunk_index 重组（v2.48.0）。
• 锁热点：__aenter__ 已改为非阻塞，但写路径仍可能排队；监控事件循环延迟可观察锁竞争。

一、目标与定位

geny-executor 的工具系统承担两件事：把 LLM 视角下的"可调用能力"（function/tool）做成一等公民；并把外部协议（MCP, Model Context Protocol）以及内部实现（vector_store、fetch_document 等）以统一方式暴露给模型。整体采用"注册—装配—执行—授权"四段式：本地工具与 MCP 工具共用同一个抽象（base.py 定义的 Tool 基类），由 registry.py 集中管理，由 provider.py 注入来源，由 composer.py 组合成工具集，最终在 sandbox.py 与 permission/matrix.py 的双重约束下被调用。资料来源：src/geny_executor/tools/base.py:1-1、src/geny_executor/tools/registry.py:1-1。

二、核心组件

2.1 Tool 基类与注册表

base.py 定义了工具的最小契约：名称、描述、JSON Schema 入参、invoke 同步/异步入口以及 to_claude_tool_spec 之类的模型描述序列化方法。registry.py 在此之上维护全局命名空间，负责同名工具的覆盖、冲突告警以及按 persona / session 的可见性过滤。CLI 的 --allowedTools / --disallowedTools 在 v2.45.1 中通过 extra_args 与 POSIX -- 终止符做了 argv 重排，确保多变长工具规则不会吞掉位置参数中的 prompt。资料来源：src/geny_executor/tools/registry.py:1-1。

2.2 Provider 与扩展点

provider.py 是真正的"来源"层：内置的本地 Provider 直接注册 Python 函数；MCP Provider 则通过外部进程（stdio / websocket）握手，按 MCP 协议枚举 tools/list 并把每条声明包装成与本地工具同构的对象返回。这意味着下游（composer、sandbox、permission）只看到统一形态，不区分来源——这就是 v2.47.0 中 FileMemoryProvider 能把 vector_store（QdrantVectorStore）注入为 VectorHandle、并被 fetch_document(ref) 这类宿主文档读取工具调用的根本原因。资料来源：src/geny_executor/tools/provider.py:1-1。

三、组合、权限与沙箱

flowchart LR
    A[Tool base.py] --> B[registry.py]
    P1[Local provider.py] --> B
    P2[MCP provider.py] --> B
    B --> C[composer.py]
    C --> D{permission/matrix.py}
    D -->|allow| E[sandbox.py]
    D -->|deny| F[阻断并返回错误]
    E --> G[Tool 执行结果]

composer.py 负责把多来源工具合并成 persona 级别的"工具集"：去重、按 priority 排序、解析 dependencies（例如 fetch_document 隐式依赖 vector_store）。permission/matrix.py 是策略矩阵：行是工具或工具族，列是 persona / 命令 / 路径模式；命中规则时输出 allow / deny / ask。结合 CLI 的 --allowedTools 过滤，v2.45.1 修复后参数解析不再误吞 prompt，矩阵的判定也因此更可靠。sandbox.py 则是执行围栏——超时取消、输出体积限制、敏感字段（API key、token）脱敏，以及 v2.48.2 中新引入的 LoopAgnosticLock 语义：即便在 vector_store.index 等 await 链路中持有锁，事件循环也不会被同步 acquire 阻塞整条回路。资料来源：src/geny_executor/tools/composer.py:1-1、src/geny_executor/tools/permission/matrix.py:1-1、src/geny_executor/tools/sandbox.py:1-1。

四、扩展机制：新增工具的三条路径

1. 纯本地实现：在 tools/ 子模块继承 Tool 基类并 @register("name")，由 registry.py 自动收编，零协议开销。资料来源：src/geny_executor/tools/base.py:1-1。
2. MCP 接入：实现一个新的 MCPProvider 子类，声明 command / args / transport，由 provider.py 在启动时拉取声明并以同构形态注入 registry，无需改动 composer 与 sandbox。资料来源：src/geny_executor/tools/provider.py:1-1。
3. 可插拔后端：例如 QdrantVectorStore 通过实现 VectorHandle 协议（fetch_document 为可选方法）让宿主工具集获得"按 ref 重组整篇文档"的能力，这是 v2.48.0 引入的重组原语。资料来源：src/geny_executor/tools/registry.py:1-1、src/geny_executor/tools/provider.py:1-1。

五、关键不变量

• 同构：本地与 MCP 工具在 registry 中形态一致，权限与沙箱不感知来源。
• 可声明依赖：composer 解析 dependencies 后才允许某些工具同时暴露，避免运行时才发现缺依赖。
• 非阻塞事件循环：v2.48.2 修复后，所有经 sandbox 执行的工具在跨 await 持锁时都不会把事件循环冻住。
• 策略优先于 CLI 过滤：permission/matrix 的判定结果最终覆盖 CLI 的 --allowedTools，避免越权。
• 可选协议方法：VectorHandle.fetch_document 这类能力通过协议上的"可选"声明向下兼容老后端。

资料来源：src/geny_executor/tools/permission/matrix.py:1-1、src/geny_executor/tools/sandbox.py:1-1。

Pitfall Log / 踩坑日志

项目：CocoRoF/geny-executor

摘要：发现 17 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：配置坑 - 可能修改宿主 AI 配置。

1. 配置坑 · 可能修改宿主 AI 配置

• 严重度：medium
• 证据强度：source_linked
• 发现：项目面向 Claude/Cursor/Codex/Gemini/OpenCode 等宿主，或安装命令涉及用户配置目录。
• 对用户的影响：安装可能改变本机 AI 工具行为，用户需要知道写入位置和回滚方法。
• 证据：capability.host_targets | https://github.com/CocoRoF/geny-executor | host_targets=mcp_host, claude_code, claude, chatgpt

2. 能力坑 · 能力判断依赖假设

• 严重度：medium
• 证据强度：source_linked
• 发现：README/documentation is current enough for a first validation pass.
• 对用户的影响：假设不成立时，用户拿不到承诺的能力。
• 证据：capability.assumptions | https://github.com/CocoRoF/geny-executor | README/documentation is current enough for a first validation pass.

3. 维护坑 · 失败模式：migration: 1.21.0 — root _index.json as bounded folder-tree summary

• 严重度：medium
• 证据强度：source_linked
• 发现：Developers should check this migration risk before relying on the project: 1.21.0 — root _index.json as bounded folder-tree summary
• 对用户的影响：Upgrade or migration may change expected behavior: 1.21.0 — root _index.json as bounded folder-tree summary
• 证据：failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v1.21.0 | 1.21.0 — root _index.json as bounded folder-tree summary

4. 维护坑 · 维护活跃度未知

• 严重度：medium
• 证据强度：source_linked
• 发现：未记录 last_activity_observed。
• 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。
• 证据：evidence.maintainer_signals | https://github.com/CocoRoF/geny-executor | last_activity_observed missing

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 证据：downstream_validation.risk_items | https://github.com/CocoRoF/geny-executor | no_demo; severity=medium

6. 安全/权限坑 · 存在评分风险

• 严重度：medium
• 证据强度：source_linked
• 发现：no_demo
• 对用户的影响：风险会影响是否适合普通用户安装。
• 证据：risks.scoring_risks | https://github.com/CocoRoF/geny-executor | no_demo; severity=medium

7. 运行坑 · 失败模式：performance: v2.46.0 — Fact Ledger + schema-bound memory

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: v2.46.0 — Fact Ledger + schema-bound memory
• 对用户的影响：Upgrade or migration may change expected behavior: v2.46.0 — Fact Ledger + schema-bound memory
• 证据：failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v2.46.0 | v2.46.0 — Fact Ledger + schema-bound memory

8. 运行坑 · 失败模式：performance: v2.46.1 — Fact Ledger round-trip fix

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: v2.46.1 — Fact Ledger round-trip fix
• 对用户的影响：Upgrade or migration may change expected behavior: v2.46.1 — Fact Ledger round-trip fix
• 证据：failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v2.46.1 | v2.46.1 — Fact Ledger round-trip fix

9. 运行坑 · 失败模式：performance: v2.47.0 — qdrant knowledge-vault vector backend

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: v2.47.0 — qdrant knowledge-vault vector backend
• 对用户的影响：Upgrade or migration may change expected behavior: v2.47.0 — qdrant knowledge-vault vector backend
• 证据：failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v2.47.0 | v2.47.0 — qdrant knowledge-vault vector backend

10. 运行坑 · 失败模式：performance: v2.48.2 — memory lock deadlock fix

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this performance risk before relying on the project: v2.48.2 — memory lock deadlock fix
• 对用户的影响：Upgrade or migration may change expected behavior: v2.48.2 — memory lock deadlock fix
• 证据：failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v2.48.2 | v2.48.2 — memory lock deadlock fix

11. 维护坑 · issue/PR 响应质量未知

• 严重度：low
• 证据强度：source_linked
• 发现：issue_or_pr_quality=unknown。
• 对用户的影响：用户无法判断遇到问题后是否有人维护。
• 证据：evidence.maintainer_signals | https://github.com/CocoRoF/geny-executor | issue_or_pr_quality=unknown

12. 维护坑 · 发布节奏不明确

• 严重度：low
• 证据强度：source_linked
• 发现：release_recency=unknown。
• 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。
• 证据：evidence.maintainer_signals | https://github.com/CocoRoF/geny-executor | release_recency=unknown

13. 维护坑 · 失败模式：maintenance: v2.45.0 — CLI vision wire fix

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2.45.0 — CLI vision wire fix
• 对用户的影响：Upgrade or migration may change expected behavior: v2.45.0 — CLI vision wire fix
• 证据：failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v2.45.0 | v2.45.0 — CLI vision wire fix

14. 维护坑 · 失败模式：maintenance: v2.45.1 — '--' guard for the positional prompt

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2.45.1 — '--' guard for the positional prompt
• 对用户的影响：Upgrade or migration may change expected behavior: v2.45.1 — '--' guard for the positional prompt
• 证据：failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v2.45.1 | v2.45.1 — '--' guard for the positional prompt

15. 维护坑 · 失败模式：maintenance: v2.47.1 — qdrant remove() without dimension guard

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2.47.1 — qdrant remove() without dimension guard
• 对用户的影响：Upgrade or migration may change expected behavior: v2.47.1 — qdrant remove() without dimension guard
• 证据：failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v2.47.1 | v2.47.1 — qdrant remove() without dimension guard

16. 维护坑 · 失败模式：maintenance: v2.48.0 — fetch_document reassembly primitive

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2.48.0 — fetch_document reassembly primitive
• 对用户的影响：Upgrade or migration may change expected behavior: v2.48.0 — fetch_document reassembly primitive
• 证据：failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v2.48.0 | v2.48.0 — fetch_document reassembly primitive

17. 维护坑 · 失败模式：maintenance: v2.48.1 — embedding input token-budget guard

• 严重度：low
• 证据强度：source_linked
• 发现：Developers should check this maintenance risk before relying on the project: v2.48.1 — embedding input token-budget guard
• 对用户的影响：Upgrade or migration may change expected behavior: v2.48.1 — embedding input token-budget guard
• 证据：failure_mode_cluster:github_release | https://github.com/CocoRoF/geny-executor/releases/tag/v2.48.1 | v2.48.1 — embedding input token-budget guard