CaveAgent
把 LLM 变成有状态运行时操作者：注入、操控、取回真实 Python 对象，突破文本进文本出的局限。
证据显示默认 IPythonRuntime 在宿主进程内直接执行 LLM 生成的代码，SecurityChecker 仅是 AST 静态规则且 README 明确承认不是沙箱，属外部效果偏大但已如实披露，故 external_effects 记 1、least_privilege 因提供进程隔离后端与延迟启动记 2；未见到任何需要用户确认危险操作的机制（user_confirmation 1）；无密钥脱敏或数据分类处理说明，示例甚至明文传入 api_key（sensitive_data_handling 1）；CI 使用 SHA 锁定的 action 与 uv.lock，依赖管理较好（dependency_security 2）；rollback 仅有 reset()/kernel 重置的零散提及（1）；MIT 许可、作者署名与 arXiv 链接使 source_attribution 记 2。
README 声称的类型化错误层级、重试/退避、熔断器、空闲超时等设计在 pyproject、CI 与测试基建（FakeModel/FailingModel、live 测试自动跳过）之间相互印证，self_consistency 记 2 而非 3，因为核心 src 代码不在证据中，无法静态核验实现与文档一致；extras 拆分与 locked 安装支持 dependency_availability 2；StopReason 等失败语义定义清晰但仅见于文档（failure_messages 2）。
受众（开发者/内部工具/多租户）与场景（可信 vs 不可信代码）划分明确，两种 runtime 后端给出对比表（audience_and_scenarios 2）；capability_boundaries 2 得益于明确的『非沙箱』警告与预算上限；技能按需激活、内核首次执行才启动体现 trigger_precision 2；Python 3.12+ 锁定与可选依赖使 environment_fit 2。未扣分到 1 是因为各项均有具体文件支撑；未给 3 是因为缺少执行验证。
README 结构完整（目录、安装、示例、特性、配置），information_architecture 3；install_notes 分 extras 说明清楚，3；naming_stability 有明确理由保留 MessageRole 历史行为并注释说明，记 2；示例覆盖广并指向具体文件（examples_and_faq 2），但无 FAQ；known_limitations 2 因安全边界与预算余量等局限被主动写出；license 文件完整有效，3；扣分点：仅有 0.8.0 Alpha 版本号、未见 CHANGELOG 或发布说明（versioning_changelog 1），无维护者治理/响应承诺（maintenance_responsibility 1），发布者身份未经验证但按规则不因此单独扣分。
对象以原生类型注入/取回、大输出持久化为运行时变量并给出可操作提示，output_usability 2；相对 JSON 工具调用的对象级数据流是清晰的差异化价值（marginal_value 2）；token/时间/成本预算、上下文压缩、批量摘要等成本控制设计充分，但均未经执行验证，故 cost_benefit 2。
README 声称指向 arXiv 论文、具体示例文件与配置字段，可静态追溯（claim_traceability 2）；README 与 pyproject/CI/测试注释相互一致，例如 [all] extra 修复的历史注释（cross_source_corroboration 2），但仓库外声明（PyPI、arXiv 内容）无法核实；文档对设计动机的推断大多以注释/说明形式与事实分离（fact_inference_separation 2）。整体因未执行任何代码而保持 low 置信。
- 默认 IPythonRuntime 在宿主进程内执行 LLM 生成的代码，SecurityChecker 仅是静态 AST 加固，官方已声明不是沙箱——处理不可信代码时必须使用 IPyKernelRuntime 并叠加容器/seccomp 等真实隔离边界。
- 未见用户确认机制：LLM 可直接操作注入的数据库连接等敏感对象，敏感场景需自行加审批层；示例中明文传递 api_key，实际使用应改用环境变量。
- 项目为 0.8.0 Alpha 且无 CHANGELOG、无维护承诺，发布者身份未经验证，生产采用前请评估供应链与升级风险。
- 本评审为静态源码评审，所有可靠性、成本与安全声明均未经执行验证。
这个 Agent 能做什么，适合哪些场景？
CaveAgent 是一个 MIT 许可的开源 Python 框架，为 LLM 智能体提供有状态的运行时管理。它突破了传统工具调用只能传 JSON 原始类型的模式，允许把 DataFrame、数据库连接、自定义类实例等任意 Python 对象直接注入运行时，作为 LLM 可以操作的一等变量，并在多轮对话中保持状态、无需序列化。框架提供两种运行时后端：进程内运行的 IPythonRuntime（默认，零拷贝直接访问对象）和进程隔离的 IPyKernelRuntime（崩溃不影响宿主进程，通过 dill 序列化注入对象）。它基于代码执行实现函数调用，支持多智能体协调、实时事件流、AST 安全规则、Agent Skills 标准（含 injection.py 扩展）、多层级上下文压缩、超大输出持久化、token 预算和 API 韧性机制。模型层支持 OpenAI 兼容接口和通过 LiteLLM 接入上百个提供商。
安装后通过 CaveAgent(model, runtime=runtime) 创建智能体。开发者用 IPythonRuntime 或 IPyKernelRuntime 声明 Variable（如数据库引擎、DataFrame）、Function（Python 函数）和 Type（类 schema），LLM 生成并执行 Python 代码直接调用这些对象的方法；执行结果留在运行时中，可用 await runtime.retrieve("name") 以原生 Python 类型取回。智能体以事件流（TextEvent、CodeEvent、ExecutionResultEvent、ThinkingChunkEvent、StoppedEvent 等）输出运行过程，支持流式渲染和多轮状态保持。多智能体模式下，编排者的运行时可注入子智能体作为一等对象进行调度。安全方面提供基于 AST 的 SecurityChecker 规则（ImportRule、FunctionRule、AttributeRule、RegexRule），文档明确其为防御加固而非沙箱。上下文压缩分两级：微压缩清理旧的执行结果，全量压缩用 LLM 摘要旧消息，并支持 CJK 感知的 token 估算和增量再压缩。
- 数据分析师需要 LLM 直接查询数据库并生成可视化配置：注入 SQLAlchemy Engine 和图表配置管理器，LLM 执行 SQL 并产出真实可渲染的 ECharts 配置对象。
- 构建需要跨多轮保持对象状态的对话应用：注入的变量在轮次间持久存在，无需把数据塞进上下文窗口或反复序列化。
- 智能家居或物联网控制场景：注入带有方法的设备类实例（如 Light、Thermostat），LLM 直接调用方法并取回更新后的对象状态。
- 多智能体数据流水线：编排智能体把清洗器和分析器子智能体作为一等变量调度，各子智能体拥有独立运行时。
- 运行不可信代码的沙箱化工作流：使用 IPyKernelRuntime 进程隔离，代码崩溃时宿主进程存活，重置内核即可继续。
- 长对话或高成本场景：通过上下文压缩、token 预算（max_total_tokens 等）和超大输出持久化控制成本与上下文占用。
这个 Agent 有哪些优点和局限？
- 对象级注入与取回是具体差异化能力：LLM 操作真实 Python 对象而非 JSON 原始类型，状态存于运行时而非上下文窗口，免去序列化开销。
- 双运行时后端可按信任级别选择：受信环境用零拷贝的 IPythonRuntime，不可信代码用崩溃隔离的 IPyKernelRuntime，且内核在首次执行代码时才延迟启动。
- 工程化韧性完善：瞬态错误指数退避重试、计费错误不重试、上下文溢出主动压缩并重试一次、流空闲超时看门狗、截断续写最多 3 次，StopReason 区分模型/运行时/内部错误。
- 超大执行输出不丢弃：完整文本绑定到运行时变量（如 _output_1），模型可切片、搜索或再解析，避免重新执行昂贵查询。
- 实现了 Agent Skills 开放标准并扩展 injection.py，技能元数据约 100 token 按需渐进加载，函数与变量注册为隐藏运行时绑定。
- SecurityChecker 是基于静态 AST 的咨询性加固而非沙箱，文档明确要求真正不可信代码需在容器配合 seccomp/gVisor 等真实隔离边界中运行，采用方需自行搭建。
- Python 3.12+ 的版本门槛较高，且核心执行依赖嵌入式 IPython；隔离运行时额外需要 IPyKernel 和 dill 依赖并引入约 1 秒启动与序列化开销。
- max_exec_timeout 需要可抢占运行时，仅 IPyKernelRuntime 支持，传给 IPythonRuntime 会在构造时抛出 ValueError。
- 进程隔离模式下注入对象经 dill 序列化，本地函数和闭包虽可工作但与进程内直接引用相比有性能与兼容性代价。
- 项目相对年轻（arXiv 论文 2026 年），社区博客与第三方评估有限，生产环境大规模采用的成熟度证据尚不充分。
如何安装或部署这个 Agent？
要求 Python 3.12+。基础安装：pip install 'cave-agent[all]'。按需选择：OpenAI 支持 pip install 'cave-agent[openai]'；通过 LiteLLM 支持上百个提供商 pip install 'cave-agent[litellm]'；进程隔离内核运行时 pip install 'cave-agent[ipykernel]'。需要准备所使用 LLM 提供商的 API key。
如何使用这个 Agent？
1) 构建模型：from cave_agent.models import LiteLLMModel; model = LiteLLMModel(model_id="model-id", api_key="your-api-key", custom_llm_provider="openai")。2) 构建运行时：from cave_agent.runtime import IPythonRuntime, Variable, Function; runtime = IPythonRuntime(variables=[Variable("secret", "!dlrow ,olleH", "A reversed message")], functions=[Function(reverse)])。3) 运行：agent = CaveAgent(model, runtime=runtime); response = await agent.run("Reverse the secret")；取回对象用 await runtime.retrieve("secret")。流式运行用 async for event in agent.stream_events(...)。隔离运行时可用 async with IPyKernelRuntime(...) as runtime 上下文管理器。关键配置参数包括 max_steps（默认 10）、context_window（默认 128000）、max_total_tokens、max_exec_timeout（仅 IPyKernelRuntime 支持）等。