在智能体框架领域，Python 生态长期占据主导地位。无论是 GenericAgent、GenomeEvolutionProtocol 还是 openai-agents-python，主流方案大多基于 Python 实现。然而，TypeScript 生态系统同样拥有强大的前端工具链和桌面应用开发能力，Craft Agents 正是这一领域的差异化方案。作为 Craft Docs 团队开源的多智能体编排框架，Craft Agents 采用 TypeScript 构建，提供桌面应用、CLI 客户端和远程服务器三种运行模式，并深度集成 Claude Agent SDK 与 Pi SDK，为开发者提供了不同于传统 CLI 工具的交互式智能体工作体验。
核心架构与设计理念
Craft Agents 的核心设计理念围绕 “Agent Native” 展开 —— 用户通过自然语言描述需求，智能体自动完成实现过程，而非依赖传统的代码编写与配置文件。这种理念贯穿于整个框架的各个层面，从前端 UI 到后端服务，从权限控制到自动化编排，均以此为基准进行构建。
框架的技术栈选择体现了现代 TypeScript 开发的最佳实践。运行时采用 Bun 以获得更快的启动速度和更优的性能表现；桌面客户端基于 Electron 与 React 构建，使用 shadcn/ui 与 Tailwind CSS v4 实现现代化的用户界面；核心智能能力则依托 Anthropic 的 Claude Agent SDK 和 Pi SDK 实现多后端支持。这种架构既保证了开发效率，又为生产环境部署提供了足够的灵活性。
从目录结构来看，项目采用 monorepo 组织方式，分为 apps 和 packages 两个主要目录。apps 目录下包含 CLI 终端客户端和 Electron 桌面应用两个入口；packages 目录则包含 core 共享类型定义和 shared 业务逻辑包，后者进一步细分为 agent 权限控制、auth 认证授权、config 配置管理、credentials 加密存储、sessions 会话持久化、sources 外部数据源集成以及 statuses 动态状态系统等模块。这种模块化设计使得框架的各个功能组件职责清晰，便于维护和扩展。
多提供者支持与模型路由
智能体框架的核心能力之一是对接各类大语言模型提供商。Craft Agents 在这一领域展现了出色的灵活性，同时支持直接连接和第三方中转两种模式。在直接连接方面，框架原生支持 Anthropic API Key 或 Claude Max/Pro OAuth 认证、Google AI Studio 的 Gemini 模型、ChatGPT Plus/Pro 的 Codex 模型以及 GitHub Copilot 的 OAuth 授权。这种多提供商支持使用户能够根据不同任务需求选择最合适的模型，无需更换工具链。
第三方与自托管支持同样完善。通过 Anthropic API Key 连接配合自定义端点配置，框架可以对接 OpenRouter 访问数百种模型（包括 Claude、GPT、Llama、Gemini 等）、Vercel AI Gateway 实现请求路由与可观测性、本地 Ollama 运行开源模型，以及任何 OpenAI 或 Anthropic 兼容的第三方 API。这种灵活性使得企业可以轻松构建混合云或本地部署的智能体基础设施。
值得注意的是，Craft Agents 采用双智能体后端架构。Claude 后端基于 npm 包 @anthropic-ai/claude-agent-sdk 实现，支持自定义基础 URL 和提供商路由，所有 Anthropic API Key、Claude Max/Pro OAuth 及第三方端点均使用此后端。Pi 后端则负责处理 Google AI Studio、ChatGPT Plus（Codex OAuth）、GitHub Copilot OAuth 及 OpenAI API Key 等连接，这类连接通过 Pi 提供商的基础设施进行路由。这种双后端设计既利用了各 SDK 的原生优势，又为用户提供了统一的使用体验。
权限控制与安全模型
企业级智能体应用对权限控制有严格要求，Craft Agents 为此设计了三级权限模式系统。Explore 模式为只读模式，阻止所有写操作，适用于需要安全探索数据或代码的场景；Ask to Edit 模式在执行写操作前提示用户确认，是默认模式，平衡了灵活性与安全性；Auto 模式则自动批准所有命令，适用于信任环境下的批量处理或自动化流程。用户可以通过快捷键 SHIFT+TAB 在会话中快速切换权限模式，这一设计使得权限控制变得直观且高效。
安全设计的另一个重要维度是本地 MCP 服务器隔离。当框架通过 stdio 传输方式启动本地 MCP 服务器时，敏感环境变量会被过滤以防止凭证泄露。被屏蔽的变量包括 ANTHROPIC_API_KEY、CLAUDE_CODE_OAUTH_TOKEN、AWS 系列凭证、GITHUB_TOKEN、OPENAI_API_KEY、Google API Key、STRIPE_SECRET_KEY 及 NPM_TOKEN 等。如需向特定 MCP 服务器显式传递环境变量，可以在源配置文件中使用 env 字段指定。这种细粒度的安全控制确保了智能体在操作外部服务时不会意外暴露敏感凭证。
凭证存储采用 AES-256-GCM 加密，确保本地保存的 API 密钥和 OAuth 凭证安全无虞。配置目录～/.craft-agent/ 下包含 config.json 主配置、credentials.enc 加密凭证存储、preferences.json 用户偏好、theme.json 主题配置，以及 workspaces 子目录下的工作区隔离配置。这种分层存储设计既保证了数据安全，又便于在不同工作区之间切换和管理。
外部数据源集成
智能体的能力边界很大程度上取决于其与外部系统交互的能力。Craft Agents 支持三种类型的外部数据源：MCP 服务器、REST API 和本地文件系统。MCP 服务器支持包括 Craft 自身、Linear、GitHub、Notion 及自定义服务器在内的广泛集成；REST API 则覆盖 Google 服务（Gmail、日历、Drive、YouTube、Search Console）、Slack 和 Microsoft 生态；本地文件系统支持直接访问文件系统、Obsidian 仓库和 Git 仓库。
外部服务连接的设计理念强调零配置体验。用户只需告诉智能体 “添加 Linear 作为数据源”，智能体便会自动查找公开 API 和 MCP 服务器、阅读文档、设置凭证并完成全部配置，无需编写配置文件或执行安装向导。对于已有 MCP 配置文件的用户，直接粘贴 JSON 即可，智能体会自动处理剩余步骤。本地 MCP 也得到完整支持，基于 stdio 的 MCP 服务器作为本地子进程运行，可以指向 npx 命令、Python 脚本或任何本地二进制文件。
对于自定义 API 集成，用户可以粘贴 OpenAPI 规范、端点 URL 或文档截图，智能体会理解并引导完成剩余配置过程。框架甚至支持通过直接 Postgres 数据库连接（在跳板机后）访问后端数据源。这种灵活的数据源集成能力使得 Craft Agents 能够适应各种复杂的企业环境和工作流程。
自动化与工作流编排
超越简单的会话交互，Craft Agents 提供了强大的自动化能力。 automations 功能允许用户通过事件触发动作来自动化工作流，支持的事件包括标签添加与移除、权限模式变更、旗标变更、会话状态变更、定时调度（cron 表达式）、工具使用前后以及会话开始与结束等。
自动化配置可以通过自然语言描述让智能体自动创建，也可以手动编辑～/.craft-agent/workspaces/{id}/automations.json 文件。例如设置工作日早上 9 点的每日站会简报、标签变为 urgent 时发送通知并总结待办事项、周五下午 5 点汇总本周完成的任务等。动作类型目前支持 prompt，即创建一个带有指定提示词的新会话，支持使用 @提及数据源和技能，并自动展开环境变量如 $CRAFT_LABEL 和 $CRAFT_SESSION_ID。
会话管理采用动态状态系统，支持自定义工作流状态（待办、进行中、需要审查、已完成等），并提供收件箱 / 归档、旗标标记、AI 生成或手动命名的会话名称，以及完整的对话历史持久化到磁盘等企业级功能。这种设计使得团队可以像管理邮件一样管理智能体会话，配合多工作区支持，非常适合需要并行处理多个项目的开发团队。
部署模式与客户端选项
Craft Agents 提供三种运行模式以适应不同场景。桌面应用模式是主要交互界面，基于 Electron 构建，提供流式响应、工具可视化、实时更新等完整体验，支持多文件差异查看（VS Code 风格窗口）和文件附件（图片、PDF、Office 文档自动转换）等高级功能。
远程服务器模式允许在 Linux VPS 等远程机器上运行头服务器，桌面应用作为瘦客户端连接。这种架构的优势在于保持长时间运行的会话活性、支持多机器访问，以及将计算密集任务卸载到强大服务器上。服务器通过 WebSocket 与客户端通信，支持 TLS 加密（生产环境推荐使用），并可通过 Docker 容器简化部署。环境变量 CRAFT_SERVER_TOKEN 用于客户端认证，支持自定义证书或反向代理终止 TLS。
CLI 客户端模式面向终端用户和自动化场景，提供 ping 健康检查、workspaces 和 sessions 列表管理、connections 和 sources 查看、session 创建与消息历史、send 消息发送与流响应、run 自包含命令（自动启动服务器、运行提示词、流响应、退出）等丰富功能。run 命令特别适合 CI/CD 流水线、服务器验证或脚本化操作，支持通过参数指定工作区目录、数据源、权限模式、LLM 提供商和模型等。
技术选型的工程考量
从工程实现角度，Craft Agents 的技术选型体现了几个关键决策。首先，选择 Bun 作为运行时而非 Node.js，获得了更快的启动速度和原生 TypeScript 支持，简化了开发流程。其次，采用 Electron + React 的组合，兼顾了跨平台桌面应用开发和现代前端工程化能力，结合 shadcn/ui 的组件库，提供了高质量的视觉体验。
核心智能能力的双 SDK 架构是一个有趣的设计选择。Claude Agent SDK 提供了强大的智能体能力，而 Pi SDK 则补充了 Google 和 OpenAI 生态的支持。这种设计避免了供应商锁定，同时让用户能够利用各平台的最优能力。然而，这种架构也意味着框架对第三方 SDK 存在依赖，需要关注 Anthropic 商业服务条款对开源项目的影响。
凭证安全和权限控制模型的设计体现了对企业级应用的重视。AES-256-GCM 加密、环境变量过滤、三级权限模式等机制为敏感环境中的部署提供了基础安全保障。MCP 服务器的本地隔离设计更是考虑到了开发者工作流的实际安全需求。
实践建议与场景适配
对于希望在 TypeScript 生态中使用智能体框架的开发者，Craft Agents 提供了一个差异化的选择。其桌面应用形态特别适合需要可视化会话管理、偏好 GUI 交互而非 CLI 的团队。多工作区支持、自动化工作流和权限控制功能使其在企业协作场景中具有优势。
需要注意的是，Craft Agents 目前主要面向桌面使用场景，对于纯服务端集成或无头运行的场景支持相对有限。虽然提供远程服务器模式和 CLI 客户端，但核心体验仍围绕桌面应用设计。如果项目需求更偏向命令行工具或无头自动化，可能需要评估其他方案。
在集成外部服务方面，框架的自然语言配置能力降低了使用门槛，但对于需要精细控制的场景，手动配置文件仍然可用。工作流自动化功能为企业级调度提供了基础设施，但目前动作类型相对有限，未来版本可能扩展更多自动化能力。
总体而言，Craft Agents 作为 TypeScript 生态的多智能体框架，在桌面应用交互、多提供商支持和自动化工作流方面展现了独特价值。对于已在使用 Craft 文档工具的团队或寻求桌面优先智能体体验的开发者，这是一个值得关注的开源方案。
资料来源：