# https://github.com/CocoRoF/geny-executor 项目说明书 生成时间：2026-07-08 10:19:16 UTC ## 目录 - [21 阶段管道与双抽象架构总览](#page-1) - [LLM 客户端与多提供者抽象](#page-2) - [记忆子系统、Fact Ledger 与向量后端](#page-3) - [工具系统、MCP 集成与扩展机制](#page-4) ## 21 阶段管道与双抽象架构总览 ### 相关页面 相关主题：[LLM 客户端与多提供者抽象](#page-2), [工具系统、MCP 集成与扩展机制](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/geny_executor/core/pipeline.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/core/pipeline.py) - [src/geny_executor/core/builder.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/core/builder.py) - [src/geny_executor/core/presets.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/core/presets.py) - [src/geny_executor/core/stage.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/core/stage.py) - [src/geny_executor/core/manifest_factory.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/core/manifest_factory.py)
# 21 阶段管道与双抽象架构总览 geny-executor 的核心运行层建立在 **21 阶段管道（Pipeline）** 与 **双抽象层（Dual Abstraction）** 之上。配置侧的 Builder 与运行侧的 Pipeline 共享 Stage 与 Manifest 这一对最小单元，在同一条端到端流水中协作，覆盖从 CLI argv 装配、混合检索、向量索引、到持久化与回执的全部副作用。 ## 双抽象：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 个阶段按职责分为四组： | 组别 | 阶段 | 职责 | |------|------|------| | 入口 | 1–4 | argv 解析、`--` 分隔、清单工厂、模式选择 | | 上下文 | 5–8 | 角色注入、事实账本、滚动摘要、混合检索 | | 推理 | 9–13 | 提示拼装、工具规则过滤、CLI 调用、流解析、视觉块保留 | | 持久化 | 14–21 | 记忆写回、事实 diff、向量索引、回执、回滚、锁释放、审计 | 入口组的 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]() ```mermaid flowchart LR A[Builder
声明侧] -->|不可变 Manifest| B[Pipeline
运行侧] 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 客户端与多提供者抽象 ### 相关页面 相关主题：[21 阶段管道与双抽象架构总览](#page-1), [工具系统、MCP 集成与扩展机制](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [src/geny_executor/llm_client/registry.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/llm_client/registry.py) - [src/geny_executor/llm_client/credentials.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/llm_client/credentials.py) - [src/geny_executor/llm_client/anthropic.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/llm_client/anthropic.py) - [src/geny_executor/llm_client/openai.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/llm_client/openai.py) - [src/geny_executor/llm_client/google.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/llm_client/google.py) - [src/geny_executor/llm_client/vllm.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/llm_client/vllm.py)
# LLM 客户端与多提供者抽象 `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` 文件，不应改写上层调用代码——这是该抽象层存在的核心目的。 --- ## 记忆子系统、Fact Ledger 与向量后端 ### 相关页面 相关主题：[21 阶段管道与双抽象架构总览](#page-1), [LLM 客户端与多提供者抽象](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [src/geny_executor/memory/_locks.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/memory/_locks.py) - [src/geny_executor/memory/facts.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/memory/facts.py) - [src/geny_executor/memory/rollup.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/memory/rollup.py) - [src/geny_executor/memory/retriever.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/memory/retriever.py) - [src/geny_executor/memory/composite/provider.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/memory/composite/provider.py) - [src/geny_executor/memory/vector/qdrant_store.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/memory/vector/qdrant_store.py)
# 记忆子系统、Fact Ledger 与向量后端 ## 概述 geny-executor 的记忆子系统负责在多次会话/轮次之间**持久化、维护并检索"知识"**，为 LLM 推理提供上下文窗口。子系统由三条主干组成： 1. **FileMemoryProvider** —— 基于本地文件的笔记/索引/汇总层，承载 `/_index.json`、`/_index.json`、`/_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` 协议，对外暴露以下原语： | 方法 | 作用 | 关键语义 | | --- | --- | --- | | `index_document(ref, chunks)` | 把一篇文档切成多个点，**payload 中存全文**并按 `chunk_index` 排序 | 是后续 `fetch_document` 重组的物理依据 | | `fetch_document(ref)` | 取回某文档**全部 chunk**，按 `chunk_index` 顺序带原文返回 | v2.48.0 新增；上层"读取整篇文档"工具的重组原语 | | `remove(filter)` | 按 filter 删除；**不带维度守护** | v2.47.1：用于切换 embedding 模型后清理旧 collection；缺失集合视为 no-op | | 混合检索 | vector + keyword 协同打分 | 由 `FileMemoryProvider.vector_store` 注入，落到 `retriever.py` 的组合路径 | 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]]() ## 端到端检索与写回 ```mermaid flowchart LR A[用户查询] --> B[composite/provider] B --> C[Fact Ledger
__facts__.md · facts_json] B --> D[Rollup v2
schema-bound JSON] B --> E[FileMemoryProvider
_index / _summary] B --> F[QdrantVectorStore
vector + keyword] C --> G[上下文拼装] D --> G E --> G F --> G G --> H[LLM] H --> I[事实 diff] I --> J[LoopAgnosticLock] J --> K[持久化
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__` 已改为非阻塞，但写路径仍可能排队；监控事件循环延迟可观察锁竞争。 --- ## 工具系统、MCP 集成与扩展机制 ### 相关页面 相关主题：[21 阶段管道与双抽象架构总览](#page-1), [LLM 客户端与多提供者抽象](#page-2)
相关源码文件 以下源码文件用于生成本页说明： - [src/geny_executor/tools/base.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/tools/base.py) - [src/geny_executor/tools/registry.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/tools/registry.py) - [src/geny_executor/tools/provider.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/tools/provider.py) - [src/geny_executor/tools/composer.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/tools/composer.py) - [src/geny_executor/tools/sandbox.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/tools/sandbox.py) - [src/geny_executor/tools/permission/matrix.py](https://github.com/CocoRoF/geny-executor/blob/main/src/geny_executor/tools/permission/matrix.py)
# 工具系统、MCP 集成与扩展机制 ## 一、目标与定位 `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]()。 ## 三、组合、权限与沙箱 ```mermaid 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]()。 --- --- ## Doramagic 踩坑日志 项目：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