koboi-agent

<div align="center"> <picture> <source media="(prefers-color-scheme: dark)" srcset="docs/assets/koboi-banner-dark.svg"> <img src="docs/assets/koboi-banner-light.svg" alt="koboi-agent" width="560"> </picture> <br/><br/> [](https://github.com/hedypamungkas/koboi-agent/actions/workflows/ci.yml) [](https://codecov.io/gh/hedypamungkas/koboi-agent) [](https://pypi.org/project/koboi-agent/) [](https://pypi.org/project/koboi-agent/) [](https://github.com/hedypamungkas/koboi-agent/blob/main/LICENSE) [](https://github.com/hedypamungkas/koboi-agent/actions/workflows/docker.yml) <br/> <strong>可自主运行且稳定的 AI 代理。</strong><br/> 具备持续运行、自主决策、安全隔离、离线回放及 CI 原生评估等功能。 <br/> <a href="#快速开始">快速开始</a> &nbsp;·&nbsp; <a href="#koboi 与其他框架的比较">与 LangGraph / CrewAI / OpenAI Agents SDK 的比较</a> &nbsp;·&nbsp; <a href="#功能">功能</a> &nbsp;·&nbsp; <a href="docs/architecture.md">架构</a> &nbsp;·&nbsp; <a href="docs/trustworthy-unattended-autonomy.md">定位</a> </div> --- > **koboi-agent** 是一个遵循 MIT 许可的 Python 异步框架，用于构建可自主运行的 AI 代理。这些代理可以执行后台作业、长时间会话、工具使用，并与实际系统交互。你可以从一个 YAML 文件中配置整个代理栈（模型、工具、防护措施、知识检索、服务），然后将其运行为命令行工具、库或自托管服务器。大多数代理框架都适用于演示；koboi 则专注于解决一个更棘手的问题：当代理崩溃、被指示执行不安全操作或无人监督时，会发生什么？ ## 为什么选择 koboi koboi 框架有四个罕见的特点，这些特点结合在一起，使代理可以安全地运行： - 🛡️ **默认稳定** — 会话在崩溃、重新部署和 `SIGKILL` 后存活。SQLite 步骤日志在每次 LLM 调用前写入一个 `running` 标记，因此 `koboi run --resume <session>` 可以恢复并重新运行 **仅未完成的工具调用** — 非幂等工具（`write_file`、`run_shell`）不会被静默重放。参见 [`benchmarks/crash_recovery/run.py`](benchmarks/crash_recovery/run.py) 以获得可重复的崩溃 -> 恢复演示。 - 🧱 **自主决策** — 代理可以行动，但仅在 seccomp 隔离的沙盒（系统调用级别的出口拒绝，无需容器）内，并具有 **默认拒绝批准**、信任数据库、速率限制和防护措施。**C3 契约**：自主破坏性作业在除非 `sandbox.backend='restricted'` 否则被 **拒绝**。 - 🔁 **离线可回放和 CI 原生** — 冻结任何运行为可重放的 bundle，可选地带有其 LLM 响应缓存，无需 **API 密钥** (`koboi capture --with-cache` → `run --replay-mode replay`)。像代码一样对待代理行为，使用 eve 风格的评估 DSL 在每个提交上运行模拟确定性 (`koboi eval-test --mock`)。 - 🏠 **自托管，无需平台升级** — `koboi serve` 是一个真正的 FastAPI 服务：交互式 SSE 聊天，具有人工干预审批 **和** 自主后台作业（Bearer 密钥、按会话所有权、幂等性、稳定恢复、HMAC 网络钩子）。在您自己的基础设施上运行 — 无需托管层即可实现稳定性和治理。 > [!NOTE] > 多个醒目功能 — **自我修复**、**主动记忆**、**基础/交接**、**多模态**、**跨实例 A2A**、**深入研究**、**确定性重放** 和 **seccomp HARD** 隔离 — 都是 **可选/默认关闭** 的，因此默认安装保持最小和可预测。每个功能都在其出现的地方记录。有关 **koboi 的局限性**，请参阅它有意精简的部分。 ## 快速开始 ```bash pip install koboi-agent export OPENAI_API_KEY=sk-... # 或 ANTHROPIC_API_KEY / CLOUDFLARE_API_KEY # （克隆了仓库？`cp .env.example .env` 然后编辑它 — koboi 自动加载 .env） ``` 从命令行一键运行（适用于裸安装，无需额外功能）： ```bash koboi run configs/simple_chat.yaml -m "2 + 2 是多少？" ``` 或作为库： ```python import asyncio from koboi import KoboiAgent async def main(): async with KoboiAgent.from_config("configs/simple_chat.yaml") as agent: result = await agent.run("2 + 2 是多少?") print(result.content) asyncio.run(main()) ``` <details> <summary><b>可选额外功能</b>（每个解锁一个功能；裸安装涵盖 <code>run</code>、<code>validate</code>、<code>keys</code>、<code>mcp-serve</code>、<code>eval-test</code>、<code>graph</code>、<code>export</code>/<code>capture</code>、<code>workflows</code>）</summary> ```bash pip install koboi-agent[tui] # 交互式 `koboi chat`（Textual TUI）+ 示例（click + rich） pip install koboi-agent[api] # `koboi serve`（FastAPI HTTP/SSE 服务器） pip install koboi-agent[tokenizer] # 准确的 OpenAI token 计数（tiktoken）；字符/3 启发式是回退 pip install koboi-agent[rerank-local] # 本地 BGE 交叉编码器重排序（jina/cohere 是托管 API，无需额外） pip install koboi-agent[indo-nlp] # 印度尼西亚词干提取器（Sastrawi）用于词汇 RAG pip install koboi-agent[media-cloud] # R2/S3 媒体工件存储（本地存储无需额外） pip install koboi-agent[rag] # RAG 文档解析器（pypdf / python-docx / pdfplumber） pip install koboi-agent[browser] # Playwright 获取提供程序（然后 `playwright install chromium`） pip install koboi-agent[tracing] # Langfuse 可观察性 pip install koboi-agent[dev,tui,api] # 所有功能（贡献者） ``` 系统软件包（非 pip）：`python3-seccomp` 用于 HARD 沙盒隔离（仅限 Linux）；`playwright install chromium` 用于浏览器获取提供程序。 </details> ## 60 秒了解：一个能抵御崩溃的代理 最快的了解差异的方法是稳定性。启动一个运行，让它在运行过程中崩溃，然后恢复： ```bash # 启动一个长时间运行的、使用工具的任务，然后在运行过程中 Ctrl-C / kill 进程 koboi run configs/simple_chat.yaml -m "读取 ./data 并总结每个文件" # 列出中断的会话并恢复它 — 只有未完成的工具调用会重新运行 koboi sessions configs/simple_chat.yaml koboi run configs/simple_chat.yaml --resume <session> ``` 可重复基准测试，带有时钟数字：`python benchmarks/crash_recovery/run.py`。 另一个“等等，它做了 **什么**？”的时刻 — **自托管服务器上的人工干预**，在裸安装上： ```bash pip install koboi-agent[api] && koboi keys create koboi serve configs/hitl_demo.yaml # 交互式 SSE 聊天，带有批准提示 python examples/hitl_client.py # httpx-only 客户端，自动解析 pending_approval 事件 ``` ## koboi 对比 koboi 的优势在于 **集成** 了稳定性 + 沙盒隔离 + 受控审批 + 自托管服务 + CI 原生评估在框架核心 — 很少有框架能找到这五个功能在一起。如果 koboi 更精简，我们会说。 | 功能 | koboi | LangChain / LangGraph | CrewAI | OpenAI Agents SDK | |---|:--:|:--:|:--:|:--:| | 多提供商 LLM | ✅ OpenAI / Anthropic / Cloudflare | ✅ 广泛 | ✅ | ✅ | | **库级别崩溃/重新部署恢复** | ✅ `--resume`，非幂等工具安全，默认开启 | ◐ checkpointer（手动连接） | — | — | | **seccomp 沙盒（无容器）+ 默认拒绝批准 + 信任数据库** | ✅ | ◐ 最小 | ◐ HITL 门控 | ◐ 容器 Sandbox Agents | | **自托管服务器：交互式 SSE + 异步作业** | ✅ `koboi serve` | ◐ LangServe / 平台 | ◐ 企业 | — | | **确定性离线重放（无需 API 密钥）** | ✅ | — | — | — | | **CI 原生评估即代码（模拟确定性）** | ✅ `koboi eval-test` | ◐ LangSmith（平台） | ◐ | — | | 多代理编排（顺序/并行/DAG/深入研究） | ✅ | ✅ LangGraph | ✅ Flows | ◐ 交接 | | MCP 客户端 **和** 服务器 | ✅ | ✅ | ◐ | ✅ | | 跨实例代理到代理（A2A + 跟踪） | ✅ | ◐ 通过平台 | ◐ | — | | 多模态生成（图像/视频/音乐/语音/STT） | ✅ | ◐ 包装器 | ◐ | ◐ 通过 API 工具 | ✅ = 一流的库级 &nbsp;·&nbsp; ◐ = 部分 / 单独产品 / 平台层 &nbsp;·&nbsp; — = 不是重点 <details> <summary><b>koboi 是什么（以及不是什么）</b></summary> koboi 是一个 **自主循环** 框架（Claude Code / AutoGPT 家族）+ 多代理协调层 — 不是像 LangGraph 或 CrewAI Flows 那样的纯工作流图引擎。它适用于 **你让它运行的代理**；如果你的主要需求是一个大型、可视的节点图运行时，LangGraph 是更强的选择。 </details> ## 功能 | 领域 | 您获得的功能 | |---|---| | **模型** | OpenAI, Anthropic, Cloudflare Workers AI; `ProviderPool` 故障转移 + 命名提供商解析器 — 无需重写代理即可切换模型 | | **工具** | 13 个内置模块（计算器、文件系统、shell、web、内存、搜索、git、子代理、任务、摄取、交接、媒体、对等）+ `@tool()` 自定义工具；同步或异步，依赖注入 | | **安全** | 输入/输出防护、策略引擎、批准处理程序、分级信任数据库、速率限制、审计跟踪、机密编辑 | | **沙盒** | 直通（默认）或受限：每个会话的工作目录、rlimits、PATH 允许列表、机密剥离环境、SOFT 令牌扫描或 **HARD seccomp** 系统调用出口拒绝（Linux） | | **内存** | 内存或 SQLite-WAL（托管步骤日志）；**主动长期记忆** （自动提取事实 → 语义召回每个回合 → 始终在上下文核心块） | | **钩子** | 15 个生命周期事件 + 24+ 个专项钩子；声明式 **外部命令钩子`（钩子：` YAML — 无需 Python） | | **RAG** | 分割（固定/句子/段落/语义）、检索（关键词/BM25/语义/混合）、交叉编码器重排序（jina/cohere/local）、查询重写/HyDE、元数据过滤器、印度尼西亚停用词+词干提取器、HTTP/S3 源 — 无需向量数据库 | | **Web** | 可插拔的搜索/获取提供程序（模拟、DuckDuckGo、Brave、Firecrawl + httpx/readability/Playwright）`web_search`/`web_fetch` | | **编排** | 关键词/LLM/混合路由；顺序、并行、DAG、条件、动态（LLM 计划）；**深入研究** 模式（计划 → 搜索 → 获取 → 覆盖门控 → 引用的报告） | | **置信度和交接** | 可选的地面防护（声明分解 + NLI 判断员，抽象时拒绝）+ `transfer_to_human` 工具 + 交接检测 + 温和交接摘要 | | **自我修复** *(可选)* | 有限的验证器地面反射 → 升级梯度（重试 → 反射 → 重新计划 → 交接）在共享恢复预算下 → `max_iterations` 上的温和降级；可选 CRITIC + 自我一致性 | | **多模态** *(可选)* | 图像/视频/音乐/语音 + 转录通过可插拔网关（Surplus；模拟离线） — 代理工具、同步/异步 REST、R2/S3 存储、预算上限 | | **跨实例 A2A** *(可选)* | `call_peer_agent` 工具 + `POST /v1/peer/invoke` 入站 + 签名代理卡发现 + W3C 跟踪传播；远程对等作为一流的编排节点 | | **确定性** *(可选)* | `koboi export`/`capture` 冻结运行 + 可选响应缓存；`run --replay-mode replay` 字节相同且 **离线** | | **MCP** | 客户端（stdio + HTTP）和服务器（`koboi mcp-serve` 暴露您的代理工具；默认为 SAFE） | | **技能** | agentskills.io 对齐、3 级渐进披露、预算感知、供应链硬化（`!cmd` shell 默认关闭） | | **评估** | eve 样式 `t` DSL + 结果断言（`calledTool`/`toolWasBlocked`/`retrievedChunk`/`completed`…）、模拟确定性、25 个评估类；BFCL/GAIA/SWE-bench/RAGAS/DeepEval 套件 | | **服务** | `koboi serve`：交互式 SSE 聊天（HITL）+ 自主作业（稳定恢复）、Bearer 密钥、所有权、幂等性、HMAC Web 钩子 | | **模式** | `chat` / `plan` / `act` / `auto` / `yolo` — 渐进式工具风险；YOLO 绕过门控但从未硬编码安全 | | **TUI** *(可选)* | 文本终端 UI：聊天、命令调色板、差异视图、会话管理器、F2 MCP 状态、F3 媒体库 | ## 服务它（HTTP/SSE** *(可选)* **：文本终端 UI：聊天、命令调色板、差异视图、会话管理器、F2 MCP 状态、F3 媒体库 | ## 构建 koboi 集成自己的代理 koboi 使用其编码代理已经使用的协议： ```bash # 将此代理的工具公开为 stdio MCP 服务器（默认为 SAFE；使用 --allow / --allow-all 来升级） koboi mcp-serve configs/simple_chat.yaml ``` 可重用、供应链硬化的 **技能** （agentskills.io 对齐）存储在 [`skills/`](skills/) 中 — `code_review`、`customer_service`、`hotel_receptionist`、`search_and_summarize`。定义您自己的，他们将被发现、预算限制并使用 fail-closed 的 `!cmd` 预处理调用。 ## 快速了解 60 秒：一个能抵御崩溃的代理 最快的了解差异的方法是稳定性。启动一个运行，让它在运行过程中崩溃，然后恢复： ```bash # 启动一个长时间运行的、使用工具的任务，然后在运行过程中 Ctrl-C / kill 进程 koboi run configs/simple_chat.yaml -m "读取 ./data 并总结每个文件" # 列出中断的会话并恢复它 — 只有未完成的工具调用会重新运行 koboi sessions configs/simple_chat.yaml koboi run configs/simple_chat.yaml --resume <session> ``` 可重复基准测试，带有时钟数字：`python benchmarks/crash_recovery/run.py`。 另一个“等等，它做了 **什么**？”的时刻 — **自托管服务器上的人工干预**，在裸安装上： ```bash pip install koboi-agent[api] && koboi keys create koboi serve configs/hitl_demo.yaml # 交互式 SSE 聊天，带有批准提示 python examples/hitl_client.py # httpx-only 客户端，自动解析 pending_approval 事件 ``` ## koboi 如何比较 koboi 的优势在于 **集成** 了稳定性 + 沙盒隔离 + 受控审批 + 自托管服务 + CI 原生评估在框架核心 — 很少有框架能找到这五个功能在一起。koboi 更精简的地方，我们会说。 | 功能 | koboi | LangChain / LangGraph | CrewAI | OpenAI Agents SDK | |---|:--:|:--:|:--:|:--:| | 多提供商 LLM | ✅ OpenAI / Anthropic / Cloudflare | ✅ 广泛 | ✅ | ✅ | | **库级别崩溃/重新部署恢复** | ✅ `--resume`，非幂等工具安全，默认开启 | ◐ checkpointer（手动连接） | — | — | | **seccomp 沙盒（无容器）+ 默认拒绝批准 + 信任数据库** | ✅ | ◐ 最小 | ◐ HITL 门控 | ◐ 容器 Sandbox Agents | | **自托管服务器：交互式 SSE + 异步作业** | ✅ `koboi serve` | ◐ LangServe / 平台 | ◐ 企业 | — | | **确定性离线重放（无需 API 密钥）** | ✅ | — | — | — | | **CI 原生评估即代码（模拟确定性）** | ✅ `koboi eval-test` | ◐ LangSmith（平台） | ◐ | — | | 多代理编排（顺序/并行/DAG/深入研究） | ✅ | ✅ LangGraph | ✅ Flows | ◐ 交接 | | MCP 客户端 **和** 服务器 | ✅ | ✅ | ◐ | ✅ | | 跨实例代理到代理（A2A + 跟踪） | ✅ | ◐ 通过平台 | ◐ | — | | 多模态生成（图像/视频/音乐/语音/STT） | ✅ | ◐ 包装器 | ◐ | ◐ 通过 API 工具 | ✅ = 一流的库级 &nbsp;·&nbsp; ◐ = 部分 / 单独产品 / 平台层 &nbsp;·&nbsp; — = 不是重点 <details> <summary><b>koboi 是什么（以及不是什么）</b></summary> koboi 是一个 **自主循环** 框架（Claude Code / AutoGPT 家族）+ 多代理协调层 — 不是像 LangGraph 或 CrewAI Flows 那样的纯工作流图引擎。它适用于 **你让它运行的代理**；如果你的主要需求是一个大型、可视的节点图运行时，LangGraph 是更强的选择。 </details> ## 功能 | 领域 | 您获得的功能 | |---|---| | **模型** | OpenAI, Anthropic, Cloudflare Workers AI; `ProviderPool` 故障转移 + 命名提供商解析器 — 无需重写代理即可切换模型 | | **工具** | 13 个内置模块（计算器、文件系统、shell、web、内存、搜索、git、子代理、任务、摄取、交接、媒体、对等）+ `@tool()` 自定义工具；同步或异步，依赖注入 | | **安全** | 输入/输出防护、策略引擎、批准处理程序、分级信任数据库、速率限制、审计跟踪、机密编辑 | | **沙盒** | 直通（默认）或受限：每个会话的工作目录、rlimits、PATH 允许列表、机密剥离环境、SOFT 令牌扫描或 **HARD seccomp** 系统调用出口拒绝（Linux） | | **内存** | 内存或 SQLite-WAL（托管步骤日志）；**主动长期记忆** （自动提取事实 → 语义召回每个回合 → 始终在上下文核心块） | | **钩子** | 15 个生命周期事件 + 24+ 个专项钩子；声明式 **外部命令钩子`（钩子：` YAML — 无需 Python） | | **RAG** | 分割（固定/句子/段落/语义）、检索（关键词/BM25/语义/混合）、交叉编码器重排序（jina/cohere/local）、查询重写/HyDE、元数据过滤器、印度尼西亚停用词+词干提取器、HTTP/S3 源 — 无需向量数据库 | | **Web** | 可插拔的搜索/获取提供程序（模拟、DuckDuckGo、Brave、Firecrawl + httpx/readability/Playwright）`web_search`/`web_fetch` | | **编排** | 关键词/LLM/混合路由；顺序、并行、DAG、条件、动态（LLM 计划）；**深入研究** 模式（计划 → 搜索 → 获取 → 覆盖门控 → 引用的报告） | | **置信度和交接** | 可选的地面防护（声明分解 + NLI 判断员，抽象时拒绝）+ `transfer_to_human` 工具 + 交接检测 + 温和交接摘要 | | **自我修复** *(可选)* | 有限的验证器地面反射 → 升级梯度（重试 → 反射 → 重新计划 → 交接）在共享恢复预算下 → `max_iterations` 上的温和降级；可选 CRITIC + 自我一致性 | | **多模态** *(可选)* | 图像/视频/音乐/语音 + 转录通过可插拔网关（Surplus；模拟离线） — 代理工具、同步/异步 REST、R2/S3 存储、预算上限 | | **跨实例 A2A** *(可选)* | `call_peer_agent` 工具 + `POST /v1/peer/invoke` 入站 + 签名代理卡发现 + W3C 跟踪传播；远程对等作为一流的编排节点 | | **确定性** *(可选)* | `koboi export`/`capture` 冻结运行 + 可选响应缓存；`run --replay-mode replay` 字节相同且 **离线** | | **MCP** | 客户端（stdio + HTTP）和服务器（`koboi mcp-serve` 暴露您的代理工具；默认为 SAFE） | | **技能** | agentskills.io 对齐、3 级渐进披露、预算感知、供应链硬化（`!cmd` shell 默认关闭） | | **评估** | eve 样式 `t` DSL + 结果断言（`calledTool`/`toolWasBlocked`/`retrievedChunk`/`completed`…）、模拟确定性、25 个评估类；BFCL/GAIA/SWE-bench/RAGAS/DeepEval 套件 | | **服务** | `koboi serve`：交互式 SSE 聊天（HITL）+ 自主作业（稳定恢复）、Bearer 密钥、所有权、幂等性、HMAC Web 钩子 | | **模式** | `chat` / `plan` / `act` / `auto` / `yolo` — 渐进式工具风险；YOLO 绕过门控但从未硬编码安全 | | **TUI** *(可选)* | 文本终端 UI：聊天、命令调色板、差异视图、会话管理器、F2 MCP 状态、F3 媒体库 | ## 提供服务（HTTP/SSE + 自主作业） ```bash pip install koboi-agent[api] koboi keys create # 创建 Bearer 密钥 koboi serve configs/server_deploy.yaml --host 0.0.0.0 --port 8080 ``` 两种路径，相同的组成：`koboi serve <config>`（内置）或 `create_app(config, extra_tools=..., extra_routes=..., approval_handler=...)`（通过代码自定义）。 ```bash # 交互式 SSE 聊天（流式令牌 + 人工干预批准） curl -N -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{"message":"2+2 是多少？"}' http://localhost:8080/v1/chat/stream # 自主作业（202 + 轮询 / SSE 重放；崩溃时稳定恢复） curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \ -d '{"message":"总结 Q3 报告"}' http://localhost:8080/v1/jobs ``` <details> <summary><b>使用 Docker 自托管（3 级自定义，无需重建）</b></summary> 发布的镜像（`ghcr.io/hedypamungkas/koboi-agent:<version>`）是一个基础层： - **挂载 YAML 配置** — `docker run -e KOBOI_CONFIG=/app/agent.yaml -v agent.yaml:/app/agent.yaml …` - **挂载扩展目录** — `docker run -e KOBOI_EXTENSIONS_DIR=/app/ext -v ext/:/app/ext …`（自定义工具 / RAG 检索器；自动添加到 `sys.path`） - **派生新镜像** — `FROM ghcr.io/hedypamungkas/koboi-agent:<version>` 用于完整的 `create_app(extra_tools=…, extra_routes=…)` 组合 参见 [`examples/docker/`](examples/docker) 以获取每个层级的运行、LLM 无需证明的示例。Cloudflare Tunnel 部署通过捆绑的 `docker-compose.yml` 提供。 </details> ## 配置 一个 YAML 文件描述整个堆栈，具有 `${ENV_VAR:default}` 插值以保持机密： ```yaml agent: name: "my-agent" system_prompt: "你是有帮助的。" mode: "chat" # chat | plan | act | auto | yolo llm: provider: "openai" # openai | anthropic | cloudflare model: "gpt-4o-mini" api_key: "${OPENAI_API_KEY}" tools: builtin: [calculator, web_search, memory_store, memory_recall] context: strategy: "smart_truncation" # noop | truncation | smart_truncation | key_facts | sliding_window max_context_tokens: 8000 rag: enabled: true retriever: "hybrid" # keyword | semantic | hybrid (BM25) top_k: 10 documents: - path: "./data/sample/product_catalog.md" guardrails: input: { max_length: 10000 } rate_limit: { max_calls_per_minute: 20 } sandbox: backend: "restricted" # passthrough (default) | restricted (+ seccomp HARD) ``` 参见 [`configs/`](configs/) 获取 39 个现成的配置文件，以及 `docs/architecture.md` 获取完整的架构。值得注意的配置文件：`self_healing_demo.yaml`、`deep_research_demo.yaml`、`workflow_export_demo.yaml`、`hitl_demo.yaml`、`a2a_instance_x.yaml`、`aegis_ops_full.yaml`（近乎完整的 32 个 `KoboiConfig` 部分在一个 DAG 协调的场景中）。 ## 架构 `KoboiAgent`（`facade.py`）是单一入口点 — 它从一个 YAML `Config` 集合了所有子系统： ```mermaid flowchart LR CFG["YAML 配置<br/>模型 · 工具 · 防护措施 · 知识检索 · 服务"] --> FAC["KoboiAgent<br/><i>facade.py</i>"] subgraph LOOP["自主循环（受控）"] AC["AgentCore<br/>+ 工具管道"] HK["HookChain<br/>15 个生命周期事件"] TR["ToolRegistry<br/>13 个内置 + 自定义"] JN["步骤日志<br/>崩溃恢复 · SQLite WAL"] SB["沙盒<br/>直通 → seccomp HARD"] TU["信任 · 批准<br/>默认拒绝"] end FAC --> LOOP LOOP --> OUT["编排器<br/>顺序 · 并行 · DAG · 深入研究"] LOOP --> SRV["koboi serve<br/>SSE 聊天 + 异步作业"] LOOP --> WF["工作流导出<br/>离线重放 · 无 API 密钥"] OUT -.->|"call_peer_agent /v1/peer/invoke"| PEER["远程对等实例<br/>(跨实例 A2A)"] ``` 深入了解（代理循环生命周期、钩子系统、工具管道、扩展点）：**[docs/architecture.md](docs/architecture.md)**。 ## 使用 koboi 从您的代理构建 koboi 使用您的编码代理已经使用的协议： ```bash # 将此代理的工具公开为 stdio MCP 服务器（默认为 SAFE；使用 --allow / --allow-all 来升级） koboi mcp-serve configs/simple_chat.yaml ``` 可重用、供应链硬化的 **技能** （agentskills.io 对齐）存储在 [`skills/`](skills/) 中 — `code_review`、`customer_service`、`hotel_receptionist`、`search_and_summarize`。定义您自己的，他们将被发现、预算限制并使用 fail-closed `!cmd` 预处理调用。 </div> ## 示例 [`examples/`](examples) 目录下包含 39 个编号的脚本，以及服务器、HITL、A2A 和工作流演示： | 范围 | 功能 | |---|---| | 01–04 | 基本聊天和工具使用 | | 05–08 | 上下文管理、RAG、防护栏 | | 09–10 | MCP 客户端/服务器 | | 11–14 | 策略、钩子、技能、自定义工具 | | 15–17 | 多代理编排、Anthropic 提供商 | | 18–24 | Harness、评估、生产设置、SWE-bench | | 25–28 | 子代理、任务、基准测试、自定义 RAG | | 29–32 | 技能、评估测试、工具选择、**沙盒 + 恢复** | | 33–34 | 声明式外部命令钩子；现代 RAG（BM25 + 重新排序） | | 35 | 基于置信度的 CS，具有人工交接 | | 36–37 | **确定性工作流导出 → 捕获 → 离线重放（无 API 密钥）** | | 38 | **自愈演示**（反射、升级梯度、优雅降级、CRITIC） | | 39 | **Aegis Ops 完整示例** — 几乎所有 32 个 `KoboiConfig` 部分在一个 DAG 编排的场景中 | | `a2a_fanout` | 跨实例 A2A via `call_peer_agent` / `/v1/peer/invoke` | | `hitl_client` | 人机协作审批客户端（裸安装安全） | | `deep_research_demo.yaml` | 覆盖率受限的引用网络研究 | ```bash pip install koboi-agent[dev,tui,api] # 示例使用 click + rich；服务器示例需要 [api] python examples/38_self_healing_demo.py --mock # 离线，无 API 密钥 python examples/37_workflow_cache_capture_replay.py # 捕获 + 离线重放 ``` ## 诚实的局限性 提前说明这些是重点 — 它们是一个值得信赖的仓库和一个充满炒作的仓库之间的区别： - **单节点热状态**。池、作业和幂等性都在进程内。`protocols.py` 接口存在于未来的 Redis/Postgres 交换，但多节点 HA **不是** 今天的声明。 - **RAG 在进程内** — 无外部向量 DB、文件系统/HTTP/S3 文档源。为自主权楔形而量身定制；LangChain/LlamaIndex 更适合纯 RAG 工作负载。 - **MCP 认证是静态 Bearer 或 OAuth2 客户端凭证**（带有令牌刷新 + 401 恢复）— 不支持交互式授权码/用户委托流，因此需要用户同意的远程 MCP 服务器仍需要手动生成的令牌。 - **不是工作流图引擎** — 协调是路由 + 自主循环上的扇出，而不是像 LangGraph 这样的视觉节点图运行时。 - **几个功能是可选/默认关闭**（自愈、主动记忆、接地/交接、多模态、A2A、深度研究、确定性重放、seccomp HARD）。默认安装设计为最小且可预测。 ## 文档 - [架构概述](docs/architecture.md) — 代理循环、钩子、工具管道、扩展点 - [值得信赖的无人值守自主权](docs/trustworthy-unattended-autonomy.md) — 定位和竞争分析 - [REST/SSE + 作业服务](docs/rest-sse-requirements.md) — 自托管服务器规范 - [自愈](docs/self-healing-strategy.md) — 有限恢复、升级梯度 - [深度研究](docs/deep-research-smoke.md) — 覆盖率受限的引用研究 - [确定性工作流导出](docs/deterministic-workflow-export-strategy.md) — 捕获和离线重放 - [RAG 生产就绪性](docs/rag-production-readiness-eval.md) — 检索和接地评估 - [自定义钩子](docs/custom-hooks.md) — 声明式外部命令钩子线协议 - [通道桥/交接](docs/channel-bridge.md) — 全渠道交接面 ## 测试 ```bash pytest # 所有测试 pytest -k "hook" # 按关键词 pytest --cov=koboi # 带有覆盖率 pytest tests/benchmarks/ -o python_files="bench_*.py" --benchmark-only # 性能回归门控 ``` ## 贡献 欢迎贡献。安装用于开发： ```bash pip install -e ".[dev,tui,api]" pytest ``` CI 运行ruff、mypy、bandit、pip-audit、构建检查和 `coverage ≥ 90` 门控，然后再合并。有关项目约定，请参见 [`.claude/`](.claude/)，并在进行重大更改前打开问题。 ## 许可证 MIT — 自托管、扩展、发布。