kdcube

<p align="center"> <img src="assets/logo.png" alt="KDCube" width="240"> </p> <p align="center"> <strong><span style="color:#16a34a;font-size:1.15em;">快速构建强大的可控AI应用，基于您可掌控的基础设施。</span></strong> </p> <p align="center"> KDCube 为开发者提供应用框架、参考 ReAct 运行时、可重用的 API/MCP 接口、事件总线和数据总线消息传递、流媒体、应用存储、定时任务/作业、小部件、命名服务集成、Claude Code/自定义代理运行时、隔离执行、租户管理、预算控制、RBAC 和会计核算作为平台原语——这样原型可以快速演变成可控的产品，而无需从头开始重建运行时。 </p> <p align="center"> <a href="https://opensource.org/license/MIT"> <img alt="MIT 许可证" src="https://img.shields.io/badge/license-MIT-16a34a"> </a> <a href="https://pypi.org/project/kdcube-cli/"> <img alt="PyPI 包" src="https://img.shields.io/pypi/v/kdcube-cli?label=kdcube-cli"> </a> <a href="https://pypistats.org/packages/kdcube-cli"> <img alt="PyPI 下载量" src="https://img.shields.io/pypi/dm/kdcube-cli?label=downloads"> </a> </p> --- <p align="center"> <img src="assets/kdcube-system.svg" width="980" alt="KDCube 系统：浏览器、MCP 客户端、API/Webhook 和 Telegram 通过其入口传输（REST、SSE/Socket.IO 流媒体、对话事件总线、数据总线、MCP）到达平台，通过 KDCube 控制平面（RBAC、预算控制、防火墙、重载/应用）进入应用——每个可部署的 AI 应用一个。每个应用都暴露提供的接口（@api、@mcp、@ui_widget、@cron、@data_bus_handler、事件总线、数据总线、流媒体、OAuth 登录/回调），消耗每个代理的接口（工具、技能、命名服务、其他应用的 @api、外部 MCP 服务器），运行代理运行时（ReAct 参考运行时、Claude Code、自定义 Python）和一个突出的隔离执行分割（特权监督者与网络和秘密 vs. 独立 UID 执行者与无网络运行不受信任/生成的代码；进程内/本地/Docker/Fargate 模式），拥有命名服务提供者角色（引用和模式、预览和操作、事件源策略、事件解析器、本体工具），并带有自定义 OAuth 授权和每个应用的配置和秘密。可重用的 SDK 组件（聊天、画布板、记忆、用法；如 Telegram、电子邮件、浏览器、渲染等集成）通过配置安装到应用中；命名空间消费者通过所有者解析共享引用。所有内容都在您自己的基础设施上运行，在您的边界内。</p> </p> ## 快速构建强大的 AI 应用，保持可控性 使用 KDCube 的第一个原因是速度：开发者可以组装聊天、工具、UI 小部件、API、MCP、事件总线流媒体、数据总线处理程序、存储、定时任务/作业、内存、命名服务对象、Claude Code/自定义代理运行时和隔离执行到一个可运行的应用中，而无需发明运行时信封。 这种速度很重要，因为第一个 AI 演示可以在一个周末交付。麻烦通常出现在 **第二个和第三个生产应用** 中，当有人必须回答： - 谁允许运行什么，哪些接口对哪些角色可见？ - 每个应用的成本是多少，我们如何限制它，以免它让我们措手不及？ - 不受信任的模型生成的代码实际上在哪里执行？ - 哪些事件允许离开我们的边界 - 哪些永远不能？ - 我们如何在不重新部署整个服务的情况下更新一个正在运行的应用？ 托管代理服务、流程构建器和代理框架分别处理其中的一部分。KDCube 关注的是应用程序构建者需要的组合：通往真实产品的快速路径，以及可控的运行时和控制平面，这些是后期很难 retrofit 的。隔离、预算控制、RBAC、会计核算和出站事件防火墙是平台的一部分，而不是您为每个应用组装的内容。 KDCube 不仅仅是一个代理框架，不仅仅是一个聊天机器人，也不仅仅是一个流程构建器。它允许团队将完整的 AI 应用 - 聊天、UI、API、MCP 接口、定时作业、配置、状态 - 作为可部署的单元称为 **应用**，并使用平台控制运行它们。 ## 适用人群 **主要：** - 运行多个 AI 应用或代理的**平台和 AI 基础设施团队**，他们需要一个具有一致治理的运行时，而不是每个应用的脚手架。 - **受监管或数据敏感型组织** - 金融服务、医疗保健、国防、政府，或任何数据、提示、工具和执行必须保持在受控基础设施内的组织。 - 打包内部 AI 工具作为可部署的受控应用的**产品/应用团队和解决方案构建者**，具有聊天、UI、API、作业、MCP、配置和拥有状态的领域。 **也适用于：** - 构建应用的**编码代理和工程师** - 文档编写得让人容易导航。 - 负责部署、预算、会计、RBAC、隔离和运行时策略的**操作员**。 如果您只需要一个一次性提示演示、纯无代码流程构建器或完全托管的供应商托管代理服务，它可能不是您要找的第一个工具。 ## 可能实现的功能 KDCube 不仅仅是一个运行聊天机器人的地方。它是一种将内部系统、文件、流程和人工审核循环转化为受控 AI 应用的方式，这些应用可以随着第一个演示的进行而增长。 - **您组织的私有 AI 应用商店。** 每个应用作为一个完整的内部产品交付，具有自己的聊天、UI、API、MCP、事件总线/数据总线消息传递、流媒体、作业、存储、配置、秘密、状态和权限。 - **领域对象让代理实际理解。** 任务、记忆、文件、事件、案件、报告 - 或您定义的任何命名空间 - 成为具有提供者拥有的模式、预览、操作和物化路径的一流引用。 - **受控的 ReAct 运行时，而不仅仅是一个模型调用。** 应用可以包括 KDCube 的时间线驱动的代理运行时，带有工具、事件源策略、ANNOUNCE、压缩、引导/跟进和命名服务物化。 - **用于生成代码的真实执行边界。** 受信任的应用逻辑和秘密与不受信任的模型生成的代码保持分离，可以通过隔离的本地、Docker、分割监督者/执行者或 Fargate 执行模式运行。 - **应用的服务网络。** 应用可以公开 API、MCP、事件总线、数据总线、定时作业、流媒体、存储、UI 和命名服务接口；可选的组合接口如 Scene 和 Pinboard 让用户和代理通过稳定的引用在这些应用之间移动上下文。 - **跨运行时的混合部署。** 不同的应用可以在不同的 KDCube 部署、租户、项目或安全区域中运行，然后在需要混合它们的解决方案时通过显式的 API、MCP、事件和命名服务接口进行互操作。 - **在真实系统的边缘进行受控自动化。** 代理可以检查、更新、引用或附加对象，只有通过配置的工具、命名空间接口和 auth-aware 提供者操作。 - **可运行的 AI 产品。** 平台团队可以查看成本、强制执行预算、隔离执行、控制表面可见性、限制事件出口并在运行时重载/应用配置。 - **可重用的智能。** 拥有命名空间的应用可以将其对象提供给其他应用、代理、API、MCP 客户端、作业、小部件、聊天和可选的画布/场景组合，而无需这些消费者了解其存储模型。 ### 看它运行 演示登录场景展示了一种可选的组合模式：几个独立的有用应用小部件在一个页面上，每个都有自己的可见性和运行时边界。一个多功能的聊天代理、一个画布板、持久的用户记忆、一个任务跟踪器、用法/经济和一个行业新闻源可以在它们被组合到场景中时作为引用交换上下文。一个运行时，多个独立的受控 AI 接口。 项目站点和演示：**https://kdcube.tech/** ## KDCube 适合哪里 这些类别有所重叠，每个类别都有其优势。KDCube 独特的组合是自托管和代码优先的，具有租户管理、预算控制、隔离执行、会计核算和**参考代理运行时**作为平台原语，而不是附加组件。 | | **KDCube** | 托管代理服务<br>(AWS / Microsoft / Google) | 流程构建器<br>(Dify / Flowise) | 代理框架<br>(LangGraph / CrewAI) | | --- | :---: | :---: | :---: | :---: | | 自托管；数据保留在您的边界内 | ✅ | 运行在他们的云中 | ✅ | 不适用（库） | | 受控运行时：租户管理、RBAC、预算控制 | ✅ | 部分，在他们的云中 | ❌ | ❌ | | 不受信任代码的隔离执行 | ✅ | 他们的沙盒 | ❌ | ❌ | | 板载参考代理运行时（ReAct） | ✅ | 他们的运行时 | ❌ | 循环；运行时是您的 | | 领域对象作为受控命名空间 | ✅ | ❌ | ❌ | ❌ | | 完整的应用（API、UI、MCP、定时作业），而不是一个循环 | ✅ | 取决于 | 仅流程 | 仅循环 | | 代码优先 | ✅ | 低代码 | 低代码 | ✅ | | 控制平面（启用/门控/重载/应用） | ✅ | 部分 | ❌ | ❌ | 表格是关于适合度，而不是排名。KDCube 的重点是治理深度和自托管运行时 - 包括参考 ReAct 代理运行时，以便您不需要自己组装租户管理、预算控制、隔离和代理循环。 ## 作为平台原语的治理 这些是安全或平台审查实际询问的部分，而在 KDCube 中，它们内置于运行时： - **隔离环境** - 一个 `tenant/project` 是一个隔离环境，具有自己的状态、预算控制和配置。一个环境托管多个应用。使用单独的环境进行 `dev`、`staging`、`prod` 或必须永远共享运行时状态的部署。 - **RBAC + 表面可见性** - 角色范围内的控制整个应用和每个单独的表面（API、小部件、MCP、作业）。 - **预算控制、速率限制和会计核算** - 经济层、项目预算、服务速率限制、价格表会计核算和账单钩子。 - **真正的信任边界** - 受信任的调用通过应用工具运行；不受信任的模型生成的代码在隔离执行中运行。这些是不可互换的。 - **出站事件防火墙** - 应用级别控制哪些事件允许离开运行时到达客户端。 - **运行时配置流程** - 启用、禁用、门控、重载和重新应用应用及其表面，而无需为每个更改重建或重新部署整个服务。 ## 您部署的内容：一个 `应用` KDCube 中的可部署 AI 应用称为 **应用** - 一个包含后端、前端、API、小部件、MCP 接口、定时作业、配置、存储和运行时行为的 **文件夹**。它不是插件或提示包装器；它是一个完整的应用程序，可以一次公开多个受控表面。KDCube 从您的本地文件系统或 Git 存储库引用加载应用。 > **兼容性说明** - 一些较低级别的配置文件、CLI 命令、路径和旧版 SDK 文档仍使用旧名称 **bundle** (`bundles.template.yaml`, `kdcube bundle ...`, `sdk/bundle/...`)。在产品和构建者面向的文档中，可部署的单元是一个 **应用**。 典型应用结构： ```text my.app@1-0/ README.md AGENTS.md release.yaml entrypoint.py # 装饰表面：API、小部件、作业、MCP、数据总线处理程序 agents/ main.py # 代理工作流，当应用使用 ReAct 时 services/ # 可重用的应用服务/适配器 tools/ # 可选的应用本地 Python 工具 skills/ # 可选的应用本地技能 config/ bundles.template.yaml bundles.secrets.template.yaml interface/ # 应用的公共接口 + OpenAPI ui/ # 主应用 + 源文件夹小部件或迷你应用 docs/ resources/ tests/ requirements.txt backend_bridge/ # 可选的 Node/TS 后端通过狭窄的桥梁 ``` 工具和技能的线路配置是 **配置优先和每个代理**：应用在 `surfaces.as_consumer.agents.<agent>.tools` 和 `surfaces.as_consumer.agents.<agent>.skills` 下声明每个代理 ID 允许使用哪些工具、命名空间、操作和技能。按代理授予能力，而不是全局。 Python 是 KDCube 原生的 Shell。选定的后端逻辑可以生活在 Node 或 TypeScript 后面，通过狭窄的桥梁 - 参见 [应用 Node 后端桥梁](app/ai-app/docs/sdk/bundle/bundle-node-backend-bridge-README.md) 和 [Node 后端边车](app/ai-app/docs/sdk/node/node-backend-sidecar-README.md)。 ## 对代理及其运行时的控制 托管是其中的一半。KDCube 还为应用作者提供对代理如何感知和采取行动的直接控制 - 大多数堆栈留下的部分： - **事件和对象如何呈现给代理。** 工具或领域对象通过 `@event_source(...)` 和事件策略 (`react_phase = block_production / timeline_projection / announce_production / compaction_projection`) 声明，及其结果如何成为时间线块和 ANNOUNCE，以及模型实际看到的内容。代理对领域对象的视图是作者的，而不是偶然的。 - **时间线和上下文策略，包括“冷”历史记录。** 上下文长度由压缩（一个硬上限，总结并删除较旧的块）和基于年龄的 TTL 剪枝限制；在一个冷缓存之后，历史记录崩溃为紧凑的语义摘要卡而不是完整的重放。您可以钩住 `on_before_compaction` / `on_after_compaction`，设置触发器（`context_max_tokens`），并调整多少最近的回合保持完整以及在哪里放置提示缓存断点。 - **数据保留和暴露。** 时间线保留基于 TTL（`cache_ttl_seconds`、`cache_keep_recent_turns`），代理可以拉入其工作空间的内容仅限于明确的读取能力。保留和暴露是配置，而不是继承的默认值。 - **自定义本体命名空间。** 应用可以通过实现 **命名服务提供者** 来拥有一个语义命名空间 - `task:`、`mem:`、`cnv:` 或您定义的命名空间。提供者拥有 refs、对象、模式、预览、操作、块渲染、文件托管和 URI 分辨率，用于该命名空间。消费者通过配置将聊天、画布和代理连接到这些表面，而无需在公共组件中嵌入应用特定的逻辑。 - **双向物化。** 代理可以拉入命名空间引用到其隔离的工作空间作为真实文件，并将代理生成的文件托管到提供者拥有的命名空间 - 在提供者的合同和调用者的身份验证上下文之下。 - **每个代理的模型路由。** 默认模型按代理角色， 可通过应用配置覆盖，再次按调用 (`bundle_call_context.role_models`，当前兼容性字段名称）。 简而言之，您决定代理看到什么，它可以触摸什么，它记住什么，以及它被允许发出什么。 ### 一个应用不限于一个运行时 一个应用不限于一个代理或一个运行时。在单个应用中，您可以组合块并为每个块提供所需的边界： - **ReAct 代理** - 板载参考代理运行时，隔离良好，用于共享和面向用户的 工作：时间线驱动的编排，每个回合的 git 隔离的工作空间，子代理，上下文压缩，ANNOUNCE，以及工具驱动的执行。它从事件总线消耗对话事件 - 用户消息，附件，**引导**（一个实时控制中断，停止活动阶段并以引导进入新的回合），以及 **跟进**（折叠到开放的回合，扩展它并带有另一个决策回合和有界的额外迭代信用）。它 **不是**基于提供者原生工具调用 - 循环由平台运行时控制，因此遵循 ReAct 合同的模型，包括非工具调用模型，可以是推理大脑。 - **Claude Code** - 用于所有者/管理员编码流程和复杂编码管道。有用，但 **不** 等同于 ReAct 代理。 - **自定义 Python 代理** - 领域特定流程。 - **隔离执行** - 不受信任的生成的代码在控制下。 - **`@venv(...)`** - 依赖项重的 Python 叶帮助程序。 同一个应用还包含普通的后端逻辑、API、小部件、定时作业和 MCP，而不需要代理运行时。流媒体和传输表面通过 REST、SSE、Socket.IO 和 MCP 运行。两个持久的入口路径保持自己的接口：**对话事件总线** 携带所有内容用于代理的时间线（消息、附件、引导、跟进、附加上下文），而 **数据总线** 携带应用范围的持久化突变（板块补丁、对象编辑）进入 `@data_bus_handler` 工作程序。 内置的 SDK/运行时功能包括 Neuro Search、渲染工具（PDF / PPTX / DOCX / HTML / PNG）、托管的共享 Playwright 浏览器运行时、自定义工具和技能，以及 MCP 连接的工具表面。## 您可以使用 KDCube 构建什么 - **内部 AI 工作台**，聊天记录、文档、任务、内存、领域小部件和可选的画布/场景组合围绕共享引用一起工作。 - **操作助手**，通过显式提供者合同检查和更新拥有系统。 - **受控任务/事件/事件系统**，附件、证据、状态更改和摘要保留在组织边界内。 - **AI 支持的 API、Webhook 和 MCP 表面**，让外部工具和编码代理人使用相同的受控功能。 - **定时 AI 管道**，用于报告、监控、抓取、审阅队列和后台丰富。 - **客户或面向员工的迷你应用**，带有自己的前端、服务器端工具、作业、配置和授权。 - **可重用的命名服务提供者**，使领域对象可用于代理人、API、MCP 客户端、作业、聊天、widgets 和可选的画布/场景组合，而泄漏实现细节。 ## 快速入门 ```bash pipx install kdcube-cli # 或: pip install kdcube-cli kdcube ``` 先决条件：Python 3.9+，Git，Docker。 KDCube 在单个机器上使用 Docker Compose 运行，相同的环境模型适用于 EC2 风格和基于 ECS 的部署。您不需要云控制平面即可开始使用。CLI 支持有指导的本地设置、描述驱动的安装、发布或源代码构建，以及本地应用程序原型设计/重载流程。 - [快速入门](app/ai-app/docs/quick-start-README.md) - [CLI 安装程序](app/ai-app/src/kdcube-ai-app/kdcube_cli/README.md) - [CLI 部署文档](app/ai-app/docs/service/cicd/cli-README.md) ## 适用于构建者和运维人员 KDCube 为工程师和编码代理提供了文档：一个紧凑的 Tier 1 编著包、一个参考应用程序、明确的配置/运行时所有权规则，以及本地运行/重载/测试指导。代理可以作为创建者、集成者、配置器、部署者或 QA 参与实际应用程序工作。 **从产品地图开始：** - [KDCube 可以做什么](app/ai-app/docs/what-you-can-do-with-kdcube-README.md) **构建应用程序（Tier 1 包，一起阅读）：** 1. [如何浏览 KDCube 应用程序文档](app/ai-app/docs/sdk/bundle/build/how-to-navigate-kdcube-docs-README.md) 2. [如何测试应用程序](app/ai-app/docs/sdk/bundle/build/how-to-test-bundle-README.md) 3. [如何编写应用程序](app/ai-app/docs/sdk/bundle/build/how-to-write-bundle-README.md) 4. [如何使用 SDK 构建块组装应用程序](app/ai-app/docs/sdk/bundle/build/how-to-assemble-bundle-with-sdk-building-blocks-README.md) 5. [应用程序运行时设置、配置和机密](app/ai-app/docs/configuration/bundle-runtime-configuration-and-secrets-README.md) 6. [如何配置和运行应用程序](app/ai-app/docs/sdk/bundle/build/how-to-configure-and-run-bundle-README.md) **参考应用程序： - [多功能参考应用程序](app/ai-app/docs/sdk/bundle/versatile-reference-bundle-README.md) · [`versatile@2026-03-31-13-36`](app/ai-app/src/kdcube-ai-app/kdcube_ai_app/apps/chat/sdk/examples/bundles/versatile@2026-03-31-13-36) 专用示例：[`with-isoruntime@2026-02-16-14-00`](app/ai-app/src/kdcube-ai-app/kdcube_ai_app/apps/chat/sdk/examples/bundles/with-isoruntime@2026-02-16-14-00) 用于直接隔离执行 · [`node.bridge.mcp@2026-04-24`](app/ai-app/src/kdcube-ai-app/kdcube_ai_app/apps/chat/sdk/examples/bundles/node.bridge.mcp@2026-04-24) 用于应用程序本地 Node/TS 后端逻辑。 **领域对象、工具和技能： - [命名空间服务](app/ai-app/docs/sdk/namespace-services/README.md) · [集成演练](app/ai-app/docs/sdk/namespace-services/integration-README.md) - [工具子系统](app/ai-app/docs/sdk/tools/tool-subsystem-README.md) · [命名服务工具](app/ai-app/docs/sdk/tools/named-services-tools-README.md) - [自定义技能](app/ai-app/docs/sdk/skills/custom-skills-README.md) - [Canvas SDK 解决方案](app/ai-app/docs/sdk/solutions/canvas/canvas-sdk-solution-README.md) - [ReAct 文档](app/ai-app/docs/sdk/agents/react) · [Claude Code 集成](app/ai-app/docs/sdk/agents/claude/claude-code-README.md) **操作： - [应用程序描述符](app/ai-app/docs/configuration/bundles-descriptor-README.md) - [运行时表面和边界](app/ai-app/docs/runtime/README.md) - [应用程序运行时](app/ai-app/docs/sdk/bundle/bundle-runtime-README.md) - [对话事件总线和数据总线](app/ai-app/docs/service/comm/conversation-event-bus-and-data-bus-README.md) - [架构](app/ai-app/docs/arch) · [服务文档](app/ai-app/docs/service) · [执行/隔离](app/ai-app/docs/exec) · [配置](app/ai-app/docs/configuration) **完整文档索引：** [app/ai-app/docs/README.md](app/ai-app/docs/README.md) --- <p align="center">_{自托管 AI 代理控制平面 · 受管 AI 运行时，带有参考 ReAct 代理 · 适用于受监管和数据敏感组织的平台和 AI 基础设施团队。}</p>