agentic_huge_data_base / wiki
页面 Onyx · 12.4 Craft 功能·DeepWiki 中文全文译文
DeepWiki 中文译文 / Onyx / 12.4

12.4 · Craft 功能（Craft Feature）

企业连接器与统一搜索 · 聚焦本章的模块关系、源码依据与实现要点。

项目Onyx 章节12.4 状态全文译文 模块界面与交互、系统架构、接口与服务契约、安装与启动
项目要点页2.5 参考项目 项目章节目录Onyx DeepWiki 原始章节Craft Feature 上一章12.3 下一章12.5
源码线索
  • backend/onyx/server/features/build/AGENTS.template.md
  • backend/onyx/server/features/build/api/models.py
  • backend/onyx/server/features/build/api/packet_logger.py
  • backend/onyx/server/features/build/api/sessions_api.py
  • backend/onyx/server/features/build/db/build_session.py
  • backend/onyx/server/features/build/sandbox/base.py
  • backend/onyx/server/features/build/sandbox/kubernetes/docker/generate_agents_md.py
  • backend/onyx/server/features/build/sandbox/kubernetes/internal/acp_exec_client.py
  • backend/onyx/server/features/build/sandbox/kubernetes/kubernetes_sandbox_manager.py
  • backend/onyx/server/features/build/sandbox/local/agent_client.py
模块标签
  • 界面与交互
  • 系统架构
  • 接口与服务契约
  • 安装与启动
  • 文档对象与元数据

章节正文

Craft 功能

原始 DeepWiki 页面https://deepwiki.com/onyx-dot-app/onyx/12.4-craft-feature

Craft 功能

相关源文件

以下文件为本 Wiki 页面的生成提供了上下文：

  • backend/onyx/server/features/build/AGENTS.template.md
  • backend/onyx/server/features/build/api/models.py
  • backend/onyx/server/features/build/api/packet_logger.py
  • backend/onyx/server/features/build/api/sessions_api.py
  • backend/onyx/server/features/build/db/build_session.py
  • backend/onyx/server/features/build/sandbox/base.py
  • backend/onyx/server/features/build/sandbox/kubernetes/docker/generate_agents_md.py
  • backend/onyx/server/features/build/sandbox/kubernetes/internal/acp_exec_client.py
  • backend/onyx/server/features/build/sandbox/kubernetes/kubernetes_sandbox_manager.py
  • backend/onyx/server/features/build/sandbox/local/agent_client.py
  • backend/onyx/server/features/build/sandbox/local/local_sandbox_manager.py
  • backend/onyx/server/features/build/sandbox/manager/directory_manager.py
  • backend/onyx/server/features/build/sandbox/tasks/tasks.py
  • backend/onyx/server/features/build/sandbox/util/agent_instructions.py
  • backend/onyx/server/features/build/session/manager.py
  • web/src/app/craft/components/BuildWelcome.tsx
  • web/src/app/craft/components/OutputPanel.tsx
  • web/src/app/craft/components/SandboxStatusIndicator.tsx
  • web/src/app/craft/components/output-panel/UrlBar.tsx
  • web/src/app/craft/contexts/UploadFilesContext.tsx
  • web/src/app/craft/hooks/useBuildStreaming.ts
  • web/src/app/craft/services/apiServices.ts
  • web/src/app/craft/types/streamingTypes.ts

目的与范围

Craft 功能（内部称为"构建模式"）是一个集成到 Onyx 中的 AI 驱动的应用生成与执行环境。它允许用户在隔离的沙箱中描述、生成并即时运行全栈 Web 应用（主要是 Next.js）。本文档详细介绍了 ENABLE_CRAFT 功能开关、Node.js 和 opencode CLI 的集成、模板管理、持久化存储架构以及基于 Kubernetes 的隔离模型。

概述与核心概念

构建模式（Craft）

Craft 实现了一条"自然语言到代码"的管线，其中大语言模型（LLM）使用专门的工具来搭建项目、编写代码并管理一个实时的开发服务器。

术语定义代码引用
opencode CLI一个用于 AI 驱动的代码修改和项目管理的专用工具。backend/onyx/server/features/build/sandbox/kubernetes/internal/acp_exec_client.py:187-191
沙箱一个隔离的环境（本地目录或 Kubernetes Pod），用于执行代码。backend/onyx/server/features/build/sandbox/base.py:69-79
ACP 协议代理控制协议（基于 stdin/stdout 的 JSON-RPC），用于流式传输思考过程和工具调用。backend/onyx/server/features/build/sandbox/kubernetes/internal/acp_exec_client.py:1-9
持久化存储跨会话存储应用制品的位置。backend/onyx/server/features/build/configs.py:51-51

来源： backend/onyx/server/features/build/session/manager.py:1-20、backend/onyx/server/features/build/configs.py:49-54

架构与数据流

Craft 功能桥接了 FastAPI 后端与 Node.js/Python 执行环境之间的差距。

系统集成图

下图将高层概念映射到负责 Craft 编排的具体代码实体。

Onyx · 系统集成图 · 图 1
Onyx · 系统集成图 · 图 1

来源： backend/onyx/server/features/build/session/manager.py:3-16、backend/onyx/server/features/build/sandbox/kubernetes/kubernetes_sandbox_manager.py:3-11、backend/onyx/server/features/build/sandbox/kubernetes/internal/acp_exec_client.py:114-120

沙箱管理模型

Onyx 支持两种主要的沙箱实现，通过 SANDBOX_BACKEND 配置选择。

1. Kubernetes 沙箱管理器

在生产环境中，KubernetesSandboxManager 提供真正的容器隔离。

  • 用户共享模型：每个用户预置一个 Pod，用于共享 files/ 目录（从 S3 同步）backend/onyx/server/features/build/sandbox/kubernetes/kubernetes_sandbox_manager.py:13-18。
  • 会话工作区：每个会话在 Pod 内通过 setup_session_workspace 使用 kubectl exec 获得一个唯一的目录 backend/onyx/server/features/build/sandbox/kubernetes/kubernetes_sandbox_manager.py:16-17。
  • 网络：Next.js 端口从 SANDBOX_NEXTJS_PORT_START 到 SANDBOX_NEXTJS_PORT_END 动态分配 backend/onyx/server/features/build/sandbox/kubernetes/kubernetes_sandbox_manager.py:105-107。
  • 清理：空闲沙箱通过 cleanup_idle_sandboxes_task 进入休眠状态，该任务在终止 Pod 前将会话输出快照到 S3 backend/onyx/server/features/build/sandbox/tasks/tasks.py:50-59。
2. 本地沙箱管理器

用于开发或单节点部署。

  • 进程隔离：使用 ProcessManager 跟踪本地子进程，而非容器 backend/onyx/server/features/build/sandbox/local/local_sandbox_manager.py:51-54。
  • 目录管理：使用 DirectoryManager 在 SANDBOX_BASE_PATH 下创建目录结构 backend/onyx/server/features/build/sandbox/local/local_sandbox_manager.py:80-86。

来源： backend/onyx/server/features/build/sandbox/kubernetes/kubernetes_sandbox_manager.py:1-35、backend/onyx/server/features/build/sandbox/local/local_sandbox_manager.py:45-60、backend/onyx/server/features/build/sandbox/tasks/tasks.py:44-65

模板与目录设置

为了确保沙箱快速启动，Onyx 使用了一个预初始化的模板系统。

目录结构

DirectoryManager 在沙箱内强制执行严格的层级结构，以确保 opencode CLI 和大语言模型（LLM）能够可预测地导航文件。

/workspace/
├── files/                     # 共享目录 - 知识库的符号链接 [只读]
└── sessions/
    └── $session_id/           # 每个会话的工作区
        ├── outputs/           # 代理的工作目录
        │   └── web/           # Next.js 项目根目录
        ├── .venv/             # Python 虚拟环境
        ├── AGENTS.md          # 动态代理指令
        ├── opencode.json      # CLI 的大语言模型（LLM）配置
        └── attachments/       # 用户为该会话上传的文件

来源： backend/onyx/server/features/build/sandbox/manager/directory_manager.py:41-56、backend/onyx/server/features/build/sandbox/kubernetes/kubernetes_sandbox_manager.py:20-30

代理指令（智能体.md）

指令基于 AGENTS.template.md 使用 generate_agent_instructions 动态生成。该文件包含：

  • 用户上下文：名称和角色 backend/onyx/server/features/build/sandbox/util/agent_instructions.py:100-115。
  • 知识来源：可用连接器（Slack、GitHub 等）的摘要 backend/onyx/server/features/build/sandbox/util/agent_instructions.py:35-81。
  • 技能：从 SKILL.md 文件中提取的可用工具描述 backend/onyx/server/features/build/sandbox/util/agent_instructions.py:182-193。
  • 附件：明确指示优先处理 attachments/ 目录中的文件 backend/onyx/server/features/build/sandbox/util/agent_instructions.py:133-163。

来源： backend/onyx/server/features/build/AGENTS.template.md:1-25、backend/onyx/server/features/build/sandbox/util/agent_instructions.py:1-12

代码执行流程

后端与沙箱之间的交互使用代理控制协议（ACP）。

ACP 执行序列

ACPExecClient 负责处理通过 Kubernetes 流进行的底层 JSON-RPC 通信。

Onyx · ACP 执行序列 · 图 2
Onyx · ACP 执行序列 · 图 2

来源： backend/onyx/server/features/build/sandbox/kubernetes/internal/acp_exec_client.py:163-191、backend/onyx/server/features/build/sandbox/kubernetes/kubernetes_sandbox_manager.py:118-154、backend/onyx/server/features/build/session/manager.py:102-120

前端集成

前端通过 useBuildSessionStore 和 processSSEStream 工具管理 Craft 体验。

关键组件
  • OutputPanel：一个标签式界面（预览、文件、制品），用于查看生成的代码和运行中的应用 web/src/app/craft/components/OutputPanel.tsx:58-65。
  • PreviewTab：通过 iframe 渲染沙箱中运行的实时 Next.js 应用 web/src/app/craft/components/OutputPanel.tsx:62-63。
  • processSSEStream：处理后端传入的数据包流，解析 JSON 数据并将其路由到用户界面 web/src/app/craft/services/apiServices.ts:28-77。
  • createSession：通过 /api/build/sessions 端点启动新沙箱和会话的预置 web/src/app/craft/services/apiServices.ts:93-114。

来源： web/src/app/craft/components/OutputPanel.tsx:1-50、web/src/app/craft/services/apiServices.ts:1-22、web/src/app/craft/api/sessions_api.py:89-106