# https://github.com/cactus-compute/cactus-hybrid 项目说明书 生成时间：2026-07-22 22:50:35 UTC ## 目录 - [Cactus Hybrid 项目概览与混合路由概念](#page-1) - [llama.cpp 补丁套件架构 (GGUF、转换、运行时、服务、测试)](#page-2) - [置信度探针与 Handoff API (Probe & Confidence)](#page-3) - [部署、跨后端使用与运维指南](#page-4) ## Cactus Hybrid 项目概览与混合路由概念 ### 相关页面 相关主题：[llama.cpp 补丁套件架构 (GGUF、转换、运行时、服务、测试)](#page-2), [置信度探针与 Handoff API (Probe & Confidence)](#page-3), [部署、跨后端使用与运维指南](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/cactus-compute/cactus-hybrid/blob/main/README.md) - [LICENSE](https://github.com/cactus-compute/cactus-hybrid/blob/main/LICENSE) - [pyproject.toml](https://github.com/cactus-compute/cactus-hybrid/blob/main/pyproject.toml) - [cactus_hybrid/__init__.py](https://github.com/cactus-compute/cactus-hybrid/blob/main/cactus_hybrid/__init__.py) - [cactus_hybrid/router.py](https://github.com/cactus-compute/cactus-hybrid/blob/main/cactus_hybrid/router.py) - [cactus_hybrid/config.py](https://github.com/cactus-compute/cactus-hybrid/blob/main/cactus_hybrid/config.py) - [cactus_hybrid/backends/local.py](https://github.com/cactus-compute/cactus-hybrid/blob/main/cactus_hybrid/backends/local.py) - [cactus_hybrid/backends/cloud.py](https://github.com/cactus-compute/cactus-hybrid/blob/main/cactus_hybrid/backends/cloud.py)
# Cactus Hybrid 项目概览与混合路由概念 ## 项目定位与目标 `cactus-hybrid` 是 Cactus 团队在其端侧推理引擎基础上扩展出的混合执行组件，目标是在同一套调用接口下，把本地（on-device）推理与远端（cloud）推理组合起来，依据运行时条件动态选择最合适的执行路径 资料来源：[README.md:1-30]()。仓库以 Python 包的形式发布，遵循许可证条款进行分发 资料来源：[LICENSE:1-15]()。项目元数据（如包名、版本、依赖）通过标准的 `pyproject.toml` 管理，便于集成到既有的 Python 工程中 资料来源：[pyproject.toml:1-40]()。 ## 混合路由核心概念 “混合路由”（Hybrid Routing）是该项目的核心抽象：当一段推理请求进入时，路由器（router）会根据一系列策略信号——例如设备算力、当前电量、网络可用性、模型尺寸、提示词长度或用户自定义规则——决定把请求委派给本地后端还是云端后端，并能够在两者之间做结果合并或回退 资料来源：[cactus_hybrid/router.py:1-60]()。这一设计避免了把“全部本地”或“全部云端”作为单一默认选项，让应用能够在隐私、时延、成本之间灵活权衡 资料来源：[README.md:30-80]()。 ```mermaid flowchart LR A[用户请求] --> B[HybridRouter] B --> C{路由策略评估} C -- 本地优先 --> D[LocalBackend] C -- 云端优先 --> E[CloudBackend] D --> F[结果合并/回退] E --> F F --> G[返回调用方] ``` ## 系统架构与组件 整个项目由入口模块、路由器、配置对象以及若干后端实现组成。`cactus_hybrid/__init__.py` 暴露了对外的顶层 API，使调用方无需关心内部模块路径即可完成推理调用 资料来源：[cactus_hybrid/__init__.py:1-20]()。 - **配置层**：`config.py` 定义了路由策略、超时阈值、降级条件等可调参数，使策略与代码逻辑解耦 资料来源：[cactus_hybrid/config.py:1-50]()。 - **路由器层**：`router.py` 实现了策略匹配与请求分发逻辑，是混合行为的中枢 资料来源：[cactus_hybrid/router.py:60-140]()。 - **本地后端**：`backends/local.py` 封装了 Cactus 原生端侧推理能力，优先保证数据不出设备 资料来源：[cactus_hybrid/backends/local.py:1-45]()。 - **云端后端**：`backends/cloud.py` 负责与远端推理服务通信，用于处理本地无法覆盖的大模型或高复杂度任务 资料来源：[cactus_hybrid/backends/cloud.py:1-45]()。 | 组件 | 角色 | 关注点 | |------|------|--------| | HybridRouter | 策略调度 | 决定本地 vs 云端 | | LocalBackend | 端侧推理 | 隐私、低时延 | | CloudBackend | 远端推理 | 大模型、长上下文 | | Config | 策略配置 | 阈值、规则、降级 | ## 配置与使用流程 典型使用流程包含三个步骤：首先在 `Config` 中声明希望的路由偏好（例如 “本地优先、超过某 token 数走云端”），然后构造 `HybridRouter` 实例并注入对应的后端对象，最后通过统一入口发起推理；路由器会自动应用策略并在必要时做后端切换或结果融合 资料来源：[cactus_hybrid/config.py:50-90]() 资料来源：[cactus_hybrid/router.py:140-200]()。通过将策略集中在配置层，`cactus-hybrid` 让开发者可以在不改业务逻辑的前提下，针对不同终端形态与网络环境调优路由行为 资料来源：[README.md:80-120]()。 --- ## llama.cpp 补丁套件架构 (GGUF、转换、运行时、服务、测试) ### 相关页面 相关主题：[Cactus Hybrid 项目概览与混合路由概念](#page-1), [置信度探针与 Handoff API (Probe & Confidence)](#page-3), [部署、跨后端使用与运维指南](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [patches/llama.cpp/README.md](https://github.com/cactus-compute/cactus-hybrid/blob/main/patches/llama.cpp/README.md) - [patches/llama.cpp/PIN](https://github.com/cactus-compute/cactus-hybrid/blob/main/patches/llama.cpp/PIN) - [patches/llama.cpp/apply.sh](https://github.com/cactus-compute/cactus-hybrid/blob/main/patches/llama.cpp/apply.sh) - [patches/llama.cpp/install.sh](https://github.com/cactus-compute/cactus-hybrid/blob/main/patches/llama.cpp/install.sh) - [patches/llama.cpp/patches/0001-gguf-py-add-gemma-4-e2b-it-hybrid-arch-with-handoff-.patch](https://github.com/cactus-compute/cactus-hybrid/blob/main/patches/llama.cpp/patches/0001-gguf-py-add-gemma-4-e2b-it-hybrid-arch-with-handoff-.patch) - [patches/llama.cpp/patches/0002-conversion-support-Gemma4E2BItHybridForCausalLM-gemm.patch](https://github.com/cactus-compute/cactus-hybrid/blob/main/patches/llama.cpp/patches/0002-conversion-support-Gemma4E2BItHybridForCausalLM-gemm.patch)
# llama.cpp 补丁套件架构 (GGUF、转换、运行时、服务、测试) ## 套件定位与目标 该补丁套件位于仓库 `patches/llama.cpp/` 目录,是一套针对上游 `llama.cpp` 项目的本地化补丁系统,核心目标是引入并稳定支持 Gemma 4 E2B It 的混合 (hybrid) 模型架构。套件覆盖了从权重存储、模型转换、推理运行时,到本地 HTTP 服务的完整链路,并配套测试入口形成闭环。 由于 Gemma 4 E2B It 是一种**包含 handoff (注意力→局部 FFN→全局 FFN) 的混合架构**,上游 `llama.cpp` 尚未原生支持,因此本套件通过补丁的方式将其纳入 `llama.cpp` 的 GGUF 元数据、转换脚本与运行时栈中。资料来源：[patches/llama.cpp/README.md:1-40]() ## 目录结构与文件职责 补丁套件采用典型的“版本锁定 + 顺序补丁 + 构建脚本”三段式布局: | 文件 / 目录 | 作用 | | --- | --- | | `patches/llama.cpp/README.md` | 套件总览与使用说明,声明补丁编号语义与维护策略 | | `patches/llama.cpp/PIN` | 记录所锁定的上游 `llama.cpp` commit/版本,保证可复现 | | `patches/llama.cpp/apply.sh` | 按顺序应用 `patches/` 目录下编号补丁到上游源码树 | | `patches/llama.cpp/install.sh` | 在打补丁后配置、编译并安装修改后的 `llama.cpp` | | `patches/llama.cpp/patches/0001-...patch` | 向 `gguf-py` 添加 `gemma4_e2b_it_hybrid` 架构枚举与 handoff 元数据 | | `patches/llama.cpp/patches/0002-...patch` | 为 `convert_hf_to_gguf.py` 增加 `Gemma4E2BItHybridForCausalLM` 的转换路径 | 资料来源：[patches/llama.cpp/README.md:1-40]()、[patches/llama.cpp/PIN:1-3]()、[patches/llama.cpp/apply.sh:1-40]()、[patches/llama.cpp/install.sh:1-40]() ## 补丁链与构建工作流 套件工作流遵循 “PIN → apply → install” 的顺序,确保对上游的修改可追溯且可重复: ```mermaid flowchart LR A[上游 llama.cpp
由 PIN 锁定] --> B[apply.sh
按编号顺序应用 patches/] B --> C[0001 gguf-py 架构扩展
含 handoff 元数据] C --> D[0002 convert 转换脚本
Gemma4E2BItHybridForCausalLM] D --> E[install.sh
cmake 编译与安装] E --> F[hybrid 版 llama.cpp
runtime + server + tests] ``` `apply.sh` 通过 `git apply` 或 `patch` 将 `patches/` 下的文件按 `0001-`、`0002-` 前缀顺序打补丁。`install.sh` 则负责执行 `cmake` 配置、`make`/`ninja` 编译,并将可执行文件安装到本地前缀,供后续 `cactus` 运行时调用。 ## GGUF 与转换支持 (运行时/服务/测试基础) 两个补丁分别覆盖**存储格式**与**权重转换**两个层面: - **补丁 0001**:`gguf-py` 侧注册新架构 `gemma4_e2b_it_hybrid`,并在 GGUF 元数据中编码 handoff (从全局注意力过渡到密集 FFN 的特殊 token/层配置),确保 GGUF 文件可被运行时正确解析。资料来源：[patches/llama.cpp/patches/0001-gguf-py-add-gemma-4-e2b-it-hybrid-arch-with-handoff-.patch:1-80]() - **补丁 0002**:在 `convert_hf_to_gguf.py` 中新增对 `Gemma4E2BItHybridForCausalLM` 的识别与转换逻辑,使 Hugging Face 权重的张量能够正确映射到 GGUF 的张量名称与形状,特别是 hybrid 部分的专家/局部权重。资料来源：[patches/llama.cpp/patches/0002-conversion-support-Gemma4E2BItHybridForCausalLM-gemm.patch:1-80]() 补丁生效后,即可在本地 `llama.cpp` 中复用其内置的 `llama-cli` 运行时、`llama-server` HTTP 服务以及单元测试入口,对 Gemma 4 E2B It hybrid 模型进行端到端的 GGUF 加载、推理与服务暴露,从而为上层 `cactus-hybrid` 提供统一的本地 LLM 推理基座。 --- ## 置信度探针与 Handoff API (Probe & Confidence) ### 相关页面 相关主题：[Cactus Hybrid 项目概览与混合路由概念](#page-1), [llama.cpp 补丁套件架构 (GGUF、转换、运行时、服务、测试)](#page-2), [部署、跨后端使用与运维指南](#page-4)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/cactus-compute/cactus-hybrid/blob/main/README.md) - [patches/llama.cpp/patches/0004-llama-add-handoff-probe-runtime-and-staging-API.patch](https://github.com/cactus-compute/cactus-hybrid/blob/main/patches/llama.cpp/patches/0004-llama-add-handoff-probe-runtime-and-staging-API.patch) - [patches/llama.cpp/patches/0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch](https://github.com/cactus-compute/cactus-hybrid/blob/main/patches/llama.cpp/patches/0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch) - [patches/llama.cpp/patches/0006-tests-add-gemma-4-e2b-it-hybrid-handoff-probe-golden.patch](https://github.com/cactus-compute/cactus-hybrid/blob/main/patches/llama.cpp/patches/0006-tests-add-gemma-4-e2b-it-hybrid-handoff-probe-golden.patch)
# 置信度探针与 Handoff API (Probe & Confidence) ## 概述与目标 `cactus-hybrid` 项目围绕"混合推理"展开：在一个统一的 LLM 服务端内串联多种规模的模型（例如完整大模型 + 轻量模型），并在 token 生成过程中按需切换执行路径。"置信度探针与 Handoff API" 是该项目的核心机制之一，负责在推理过程中检测当前路径的生成质量，并在满足条件时将控制权（Handoff）从重模型交还给轻量级解码阶段。 其核心目的包括： - **可观察性**：暴露每一次探针的原始分数、归一化后的置信度以及阶段切换原因； - **可控性**：提供运行时（runtime）与暂存（staging）两套 API，使上层调用方既能立即读出结果，也能缓存以待后续比对； - **可移植性**：通过 server 端的 patch（`0005`）将探针结果标准化，并以 JSON 形式输出到日志或响应字段； - **可验证性**：通过黄金用例 patch（`0006`）锁定 Gemma 4 E2B-IT 在 Hybrid 模式下的预期行为，避免回归。 资料来源：[README.md:1-80]() ## 运行时与暂存 API `0004-llama-add-handoff-probe-runtime-and-staging-API.patch` 是整个特性的底层入口，向 `llama.cpp` 的 C/C++ 上下文结构中新增了一组用于"探针—决策—暂存"的接口。其主要数据结构与函数可分为三层： 1. **运行时层（Runtime）**：在每一轮 token 评估之后立即触发，不阻塞当前 `decode` 循环，向调用方回传当前 logits 的统计信息（top-k 概率、熵、归一化得分）； 2. **决策层（Decision）**：依据运行时层产出的指标计算 `confidence ∈ [0, 1]`，并对照预设阈值判断是否触发 Handoff； 3. **暂存层（Staging）**：将未立即消费的探针结果写入环形缓冲区，供上层在后续 N 个 token 内按需比对或回滚。 | 层 | 关键作用 | 典型调用时机 | | --- | --- | --- | | Runtime | 计算原始指标 | 每次 `llama_decode` 之后 | | Decision | 阈值判定 | Runtime 完成后同步执行 | | Staging | 缓存历史值 | Handoff 触发前预读 | 这种"探针 + 暂存"的组合可以避免在低置信度时直接打断生成路径，而是把决策信息累积到 staging 区域，让上层策略（例如调度器、UI）拥有完整上下文。 资料来源：[patches/llama.cpp/patches/0004-llama-add-handoff-probe-runtime-and-staging-API.patch:1-120]() ## 服务端置信度报告（Gemma 4 E 系列） `0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch` 负责把底层探针结果桥接到 HTTP/Server 端。当模型是 Gemma 4 E 系列（例如 `gemma-4-e2b-it`）且运行在 Hybrid 模式下时，Server 会在响应体与日志中追加 `handoff_probe` 字段，结构大致如下： - `probe_score`：归一化后的置信度（0–1）； - `harness`：触发探针的执行阶段标识（如 `draft`、`verify`、`fallback`）； - `decision`：`accept` / `handoff` / `defer` 三态； - `staging_ref`：指向暂存层中保留该决策的引用 id，便于客户端做长程一致性校验。 服务端通过统一的字段名对外暴露，使得不同模型（例如未来加入的更大规模 E 系列变体）可以共享同一套前端埋点和 A/B 框架。 资料来源：[patches/llama.cpp/patches/0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch:1-90]() ## 测试与黄金用例 `0006-tests-add-gemma-4-e2b-it-hybrid-handoff-probe-golden.patch` 为该特性引入了端到端的"黄金用例"（golden test）。它在 `tests/` 目录下登记了一组固定的输入 prompt 与 Hybrid 配置，运行后将输出与 `*.golden` 文件逐字段对比： ```text prompt: "请简要说明 Hybrid 推理的优势。" expected.handoff_probe.decision = "handoff" expected.handoff_probe.probe_score ∈ [0.62, 0.81] expected.staging_ref 必须非空 ``` 这一用例既覆盖了运行时层的阈值边界，又覆盖了暂存层的引用完整性，是验证 `0004` 与 `0005` 协同行为的关键保障。任何对阈值、字段名或 staging 行为的修改都必须同步更新对应的 golden 文件，否则 CI 立即失败。 资料来源：[patches/llama.cpp/patches/0006-tests-add-gemma-4-e2b-it-hybrid-handoff-probe-golden.patch:1-140]() ## 工作流总览 ```mermaid flowchart LR A[llama_decode] --> B[Probe Runtime] B --> C{confidence ≥ threshold?} C -- 是 --> D[写入 Staging
decision=accept] C -- 否 --> E[写入 Staging
decision=handoff] D --> F[继续当前路径] E --> G[Server 报告 handoff_probe] G --> H[客户端/调度器触发 Handoff] ``` 整条链路强调"先观察、后决策、再切换"的解耦思想：探针只负责客观测量，决策由 Server 层统一输出，Handoff 动作由上层策略最终执行，从而让 Hybrid 推理在可控、可解释的前提下运行。 资料来源：[README.md:60-120](), [patches/llama.cpp/patches/0004-llama-add-handoff-probe-runtime-and-staging-API.patch:60-200](), [patches/llama.cpp/patches/0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch:30-110](), [patches/llama.cpp/patches/0006-tests-add-gemma-4-e2b-it-hybrid-handoff-probe-golden.patch:20-160]() --- ## 部署、跨后端使用与运维指南 ### 相关页面 相关主题：[Cactus Hybrid 项目概览与混合路由概念](#page-1), [llama.cpp 补丁套件架构 (GGUF、转换、运行时、服务、测试)](#page-2), [置信度探针与 Handoff API (Probe & Confidence)](#page-3)
相关源码文件 以下源码文件用于生成本页说明： - [README.md](https://github.com/cactus-compute/cactus-hybrid/blob/main/README.md) - [patches/llama.cpp/install.sh](https://github.com/cactus-compute/cactus-hybrid/blob/main/patches/llama.cpp/install.sh) - [patches/llama.cpp/apply.sh](https://github.com/cactus-compute/cactus-hybrid/blob/main/patches/llama.cpp/apply.sh) - [patches/llama.cpp/patches/0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch](https://github.com/cactus-compute/cactus-hybrid/blob/main/patches/llama.cpp/patches/0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch) - [scripts/prepare.sh](https://github.com/cactus-compute/cactus-hybrid/blob/main/scripts/prepare.sh) - [scripts/run-server.sh](https://github.com/cactus-compute/cactus-hybrid/blob/main/scripts/run-server.sh) - [scripts/build-cross.sh](https://github.com/cactus-compute/cactus-hybrid/blob/main/scripts/build-cross.sh) - [tools/init.sh](https://github.com/cactus-compute/cactus-hybrid/blob/main/tools/init.sh) - [configs/server.yaml](https://github.com/cactus-compute/cactus-hybrid/blob/main/configs/server.yaml) - [docker/Dockerfile](https://github.com/cactus-compute/cactus-hybrid/blob/main/docker/Dockerfile) - [docs/deployment.md](https://github.com/cactus-compute/cactus-hybrid/blob/main/docs/deployment.md) - [docs/backends.md](https://github.com/cactus-compute/cactus-hybrid/blob/main/docs/backends.md)
# 部署、跨后端使用与运维指南 本指南聚焦 cactus-hybrid 在生产或开发环境的部署、跨推理后端（Cactus 原生后端与 llama.cpp 衍生后端）切换、以及日常运维关键操作。仓库通过 `patches/`、`scripts/`、`tools/`、`configs/`、`docker/` 五个目录协同提供一站式安装—补丁—构建—运行链路；运维则围绕启动脚本、日志路径、握手探针（handoff probe）三方面展开 资料来源：[README.md:1-80]()。 ## 部署流程与脚本编排 仓库建议以 `patches/llama.cpp/install.sh` 与 `patches/llama.cpp/apply.sh` 作为安装入口：前者负责克隆并检出与本仓兼容的 llama.cpp 子版本，后者按顺序叠加 `patches/llama.cpp/patches/0001-…` 至 `0005-…` 系列补丁，确保 llama-server 暴露本仓自定义的“握手探针置信度”字段；随后通过 `scripts/prepare.sh` 准备模型与 tokenizer 缓存目录，`scripts/run-server.sh` 启动 HTTP 推理服务 资料来源：[patches/llama.cpp/install.sh:1-40]()、资料来源：[patches/llama.cpp/apply.sh:1-40]()、资料来源：[scripts/prepare.sh:1-40]()、资料来源：[scripts/run-server.sh:1-40]()。 跨平台发布可借助 `scripts/build-cross.sh`，通常会针对 `linux/amd64`、`linux/arm64` 矩阵分别执行 CMake 与 `cactus` 静态库构建，并在产物阶段携带 llama-server 主可执行文件；容器化路径则可直接基于 `docker/Dockerfile` 构建，其中固化了相同的补丁顺序与构建参数 资料来源：[scripts/build-cross.sh:1-40]()、资料来源：[docker/Dockerfile:1-40]()。 ## 跨后端切换与配置 cactus-hybrid 同时支持“原生 Cactus 后端”与“llama.cpp 派生后端”，二者通过 `configs/server.yaml` 的 `backend:` 字段切换： | 字段 | 取值示例 | 说明 | | --- | --- | --- | | `backend.type` | `cactus` / `llama_cpp` | 选择推理内核 | | `backend.model_path` | `/models/gemma-4-e.Q4_K_M.gguf` | GGUF 权重路径 | | `backend.context_size` | `8192` | 上下文窗口 | | `server.host` / `server.port` | `0.0.0.0` / `8080` | 监听地址 | | `server.report_handoff_probe` | `true` | 上报 `X-Cactus-Probe-Confidence` | 切换后端时，`tools/init.sh` 会调用对应后端的健康检查端点（`/health` 与 `/v1/models`），验证模型加载与握手探针字段是否存在；若字段缺失，则说明 `patches/llama.cpp/patches/0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch` 未应用或顺序错误，应回到 `patches/llama.cpp/apply.sh` 重新应用 资料来源：[configs/server.yaml:1-40]()、资料来源：[tools/init.sh:1-40]()、资料来源：[patches/llama.cpp/patches/0005-server-report-handoff-probe-confidence-for-gemma-4-e.patch:1-40]()。 ## 部署架构概览 ```mermaid flowchart LR A[客户端请求] --> B[Cactus 路由层] B -- backend=cactus --> C[Cactus 原生引擎] B -- backend=llama_cpp --> D[llama-server
含 handoff probe] C --> E[模型权重 GGUF] D --> E D -- X-Cactus-Probe-Confidence --> B ``` `docs/deployment.md` 强调：Cactus 路由层读取 `X-Cactus-Probe-Confidence` 后决定是否将请求“交接（handoff）”给原生后端以获得更高吞吐，因此部署时务必保证 llama-server 补丁被正确打上，否则路由降级为单一后端 资料来源：[docs/deployment.md:1-40]()。 ## 运维关键操作 1. **补丁一致性检查**：定期在 CI 中执行 `bash patches/llama.cpp/apply.sh --check`，确保 `0005-` 补丁随升级持续生效。 2. **健康探活**：`scripts/run-server.sh` 默认暴露 `/healthz`（Cactus 后端）与 llama-server 的 `/health`；二者任一返回 200 才视为集群健康。 3. **日志与指标**：容器化部署时建议挂载 `/var/log/cactus` 目录，并通过 llama-server 的 `--log-format json` 抓取 `probe_confidence` 指标用于回溯交接决策。 4. **滚动升级**：先替换 `docker/Dockerfile` 产物，再以蓝绿方式切换 `configs/server.yaml` 中 `server.report_handoff_probe` 字段，最后执行 `scripts/prepare.sh` 预热新权重。 跨后端灰度策略可参考 `docs/backends.md`，其中描述了基于 `X-Cactus-Probe-Confidence` 阈值（例如 `>= 0.85`）在两个后端间分配流量的方法 资料来源：[docs/backends.md:1-40]()、资料来源：[README.md:60-80]()。 --- --- ## Doramagic 踩坑日志 项目：cactus-compute/cactus-hybrid 摘要：发现 7 个潜在踩坑项，其中 0 个为 high/blocking；最高优先级：身份坑 - 仓库名和安装名不一致。 ## 1. 身份坑 · 仓库名和安装名不一致 - 严重度：medium - 证据强度：runtime_trace - 发现：仓库名 `cactus-hybrid` 与安装入口 `cactus-compute` 不完全一致。 - 对用户的影响：用户照着仓库名搜索包或照着包名找仓库时容易走错入口。 - 复现命令：`pip install cactus-compute` - 证据：identity.distribution | https://news.ycombinator.com/item?id=49010782 | repo=cactus-hybrid; install=cactus-compute ## 2. 能力坑 · 能力判断依赖假设 - 严重度：medium - 证据强度：source_linked - 发现：README/documentation is current enough for a first validation pass. - 对用户的影响：假设不成立时，用户拿不到承诺的能力。 - 证据：capability.assumptions | https://news.ycombinator.com/item?id=49010782 | README/documentation is current enough for a first validation pass. ## 3. 维护坑 · 维护活跃度未知 - 严重度：medium - 证据强度：source_linked - 发现：未记录 last_activity_observed。 - 对用户的影响：新项目、停更项目和活跃项目会被混在一起，推荐信任度下降。 - 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49010782 | last_activity_observed missing - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 证据：downstream_validation.risk_items | https://news.ycombinator.com/item?id=49010782 | no_demo; severity=medium ## 5. 安全/权限坑 · 存在评分风险 - 严重度：medium - 证据强度：source_linked - 发现：no_demo - 对用户的影响：风险会影响是否适合普通用户安装。 - 证据：risks.scoring_risks | https://news.ycombinator.com/item?id=49010782 | no_demo; severity=medium ## 6. 维护坑 · issue/PR 响应质量未知 - 严重度：low - 证据强度：source_linked - 发现：issue_or_pr_quality=unknown。 - 对用户的影响：用户无法判断遇到问题后是否有人维护。 - 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49010782 | issue_or_pr_quality=unknown ## 7. 维护坑 · 发布节奏不明确 - 严重度：low - 证据强度：source_linked - 发现：release_recency=unknown。 - 对用户的影响：安装命令和文档可能落后于代码，用户踩坑概率升高。 - 证据：evidence.maintainer_signals | https://news.ycombinator.com/item?id=49010782 | release_recency=unknown