Craft Agents

工作原理（视频）

要了解 Craft Agents 的功能和工作方式，请观看以下视频。

点击此处（或上方图片）在 YouTube 上观看视频 →

开发 Craft Agents 的初衷

Craft Agents 是我们（craft.do 团队）为高效使用智能体而开发的工具。它支持直观的多任务处理，可直接连接任何 API 或服务，支持会话共享，并提供以文档（而非代码）为中心的工作流程，所有这些都集成在美观流畅的用户界面中。

它同时使用 Claude Agent SDK 和 Pi SDK，在借鉴两者优势的基础上，对我们认为有待改进的地方进行了优化。

它的设计遵循“原生智能体软件”原则，开箱即可高度自定义，是同类工具中的先行者之一。

Craft Agents 基于 Apache 2.0 许可证开源，您可以自由修改、调整任何内容。这一点确实可以实现：我们团队完全使用 Craft Agents 来开发 Craft Agents，无需代码编辑器，因此任何自定义都只需一个提示即可完成。

我们开发 Craft Agents，是因为我们需要一种更好、更具针对性（且最好是非命令行）的方式来使用世界上最强大的智能体。我们将根据自身经验和直觉，持续改进它。

那些难以置信却“就是能用”的功能

我该如何连接 Linear、Gmail、Slack……？ 告诉智能体“添加 Linear 作为数据源”。它会自动查找公开 API 和 MCP 服务器，阅读相关文档，设置凭证并完成所有配置。无需配置文件，也不需要设置向导。

查看我如何一键连接 Slack →

我已经有 MCP 配置 JSON 了。 直接粘贴即可。智能体会处理剩下的所有事情。

本地 MCP 呢？ 完全支持。基于标准输入输出的 MCP 服务器会作为本地子进程在您的机器上运行。您可以将其指向 npx 命令、Python 脚本或任何本地二进制文件。就是这么简单。

它能处理自定义 API 吗？ 可以。粘贴 OpenAPI 规范、一些端点 URL、文档截图，任何您有的信息都可以。它会自行分析并引导您完成后续步骤。

连 API 也能处理？不只是 MCP？ Craft Agents 可以连接任何事物。我们甚至将其连接到了堡垒机后的直接 Postgres 数据库。技能 + 数据源 = 神奇效果。

如何导入我的 Claude Code 技能和 MCP？ 告诉智能体您想从 Claude Code 导入技能。它会处理迁移过程。

我一次性导入了所有技能 →

如何创建新技能？ 描述技能应实现的功能，并提供相关上下文。智能体会负责其余的工作。

修改后需要重启吗？ 不需要。所有更改都是即时生效的。即使在对话过程中，也可以用 @ 提及新的技能或数据源。

所以我可以问它任何问题？ 是的。这就是“智能体原生软件”的核心理念。您描述想要什么，它会想办法实现。这才是对 tokens 的有效利用。

安装

一行安装（推荐）

macOS / Linux：

curl -fsSL https://agents.craft.do/install-app.sh | bash

Windows（PowerShell）：

irm https://agents.craft.do/install-app.ps1 | iex

从源代码构建

git clone https://github.com/lukilabs/craft-agents-oss.git
cd craft-agents-oss
bun install
bun run electron:start

功能特性

• 多会话收件箱：具备会话管理、状态工作流和标记功能的桌面应用
• Claude 代码体验：流式响应、工具可视化、实时更新
• 多 LLM 连接：添加多个 AI 提供商并设置每个工作区的默认选项
• 多提供商支持：除 Anthropic 外，还可使用 Google AI Studio、ChatGPT Plus、GitHub Copilot 或 OpenAI API 密钥运行会话
• Craft MCP 集成：访问 32 种以上 Craft 文档工具（区块、集合、搜索、任务等）
• 数据源：连接 MCP 服务器、REST API（Google、Slack、Microsoft）和本地文件系统
• 权限模式：三级系统（浏览、请求编辑、自动），支持自定义规则
• 后台任务：运行长时间操作并跟踪进度
• 动态状态系统：可自定义的会话工作流状态（待办、进行中、已完成等）
• 主题系统：应用和工作区级别的级联主题
• 多文件差异对比：VS Code 风格窗口，用于查看一轮对话中的所有文件更改
• 技能：按工作区存储的专用代理指令
• 文件附件：拖放图片、PDF、Office 文档并自动转换
• 自动化：事件驱动型自动化 — 在标签更改、计划任务、工具使用等场景下创建代理会话

快速入门

1. 启动应用：安装后启动应用程序
2. 选择 API 连接：使用 Anthropic（API 密钥或 Claude Max）、Google AI Studio、ChatGPT Plus（Codex OAuth）或 GitHub Copilot OAuth
3. 创建工作区：设置工作区以组织您的会话
4. 连接数据源（可选）：添加 MCP 服务器、REST API 或本地文件系统
5. 开始聊天：创建会话并与 Claude 交互

桌面应用功能

会话管理

• 收件箱/归档：按工作流状态组织会话
• 标记：标记重要会话以便快速访问
• 状态工作流：待办 → 进行中 → 需要审核 → 已完成
• 会话命名：AI 生成标题或手动命名
• 会话持久性：完整对话历史保存到磁盘

来源

将外部数据源连接到您的工作区：

类型	示例
MCP 服务器	Craft、Linear、GitHub、Notion、自定义服务器
REST API	Google（Gmail、Calendar、Drive、YouTube、Search Console）、Slack、Microsoft
本地文件	文件系统、Obsidian 库、Git 仓库

权限模式

模式	显示名称	行为
safe	浏览	只读，阻止所有写入操作
ask	请求编辑	提示进行批准（默认）
allow-all	自动	自动批准所有命令

在聊天界面中使用 SHIFT+TAB 循环切换模式。

键盘快捷键

快捷键	操作
Cmd+N	新建聊天
Cmd+1/2/3	聚焦侧边栏/列表/聊天
Cmd+/	键盘快捷键对话框
SHIFT+TAB	循环切换权限模式
Enter	发送消息
Shift+Enter	新行

远程服务器（无头模式）

Craft Agents 可以在远程机器（例如 Linux VPS）上以无头服务器模式运行，桌面应用程序作为瘦客户端进行连接。这使您能够保持长时间运行的会话活跃，从多台机器访问它们，并在功能强大的服务器上运行计算密集型任务。

快速开始

从 monorepo 根目录：

# Generate a token and start the server
CRAFT_SERVER_TOKEN=$(openssl rand -hex 32) bun run packages/server/src/index.ts

服务器在启动时会打印连接详情：

CRAFT_SERVER_URL=ws://203.0.113.5:9100
CRAFT_SERVER_TOKEN=<generated-token>

复制这些值，用于连接桌面应用。

连接桌面应用

通过传入服务器 URL 和令牌，以瘦客户端模式启动 Electron 应用：

CRAFT_SERVER_URL=wss://203.0.113.5:9100 CRAFT_SERVER_TOKEN=<token> bun run electron:start

在瘦客户端模式下，桌面应用负责渲染用户界面，而所有会话逻辑、工具执行和LLM调用均在远程服务器上运行。

环境变量

变量	是否必填	默认值	描述
CRAFT_SERVER_TOKEN	是	—	用于客户端认证的Bearer令牌
CRAFT_RPC_HOST	否	127.0.0.1	绑定地址（0.0.0.0 允许远程访问）
CRAFT_RPC_PORT	否	9100	绑定端口
CRAFT_RPC_TLS_CERT	否	—	PEM证书文件路径（启用 wss://）
CRAFT_RPC_TLS_KEY	否	—	PEM私钥文件路径（与证书配套使用）
CRAFT_RPC_TLS_CA	否	—	PEM CA链文件路径（可选，用于客户端证书验证）
CRAFT_DEBUG	否	false	启用调试日志

TLS（远程访问推荐）

当通过网络暴露服务器时，TLS可加密WebSocket连接（使用 wss:// 而非 ws://）。

生成自签名证书（开发/测试环境）：

./scripts/generate-dev-cert.sh
# Creates certs/cert.pem and certs/key.pem (valid 365 days)

使用TLS启动服务器：

CRAFT_SERVER_TOKEN=<token> \
CRAFT_RPC_HOST=0.0.0.0 \
CRAFT_RPC_TLS_CERT=certs/cert.pem \
CRAFT_RPC_TLS_KEY=certs/key.pem \
bun run packages/server/src/index.ts

服务器将打印 CRAFT_SERVER_URL=wss://<your-public-ip>:9100。

对于生产环境，请使用受信任 CA 颁发的证书（例如 Let's Encrypt），或将服务器部署在可终止 TLS 的反向代理（nginx、Caddy）之后。

Docker

docker run -d \
  -p 9100:9100 \
  -e CRAFT_SERVER_TOKEN=<token> \
  -e CRAFT_RPC_HOST=0.0.0.0 \
  -v craft-data:/root/.craft-agent \
  craft-agents-server

要在 Docker 中启用 TLS，请挂载您的证书并设置环境变量：

docker run -d \
  -p 9100:9100 \
  -e CRAFT_SERVER_TOKEN=<token> \
  -e CRAFT_RPC_HOST=0.0.0.0 \
  -e CRAFT_RPC_TLS_CERT=/certs/cert.pem \
  -e CRAFT_RPC_TLS_KEY=/certs/key.pem \
  -v ./certs:/certs:ro \
  -v craft-data:/root/.craft-agent \
  craft-agents-server

CLI 客户端

一款通过 WebSocket（ws:// 或 wss://）连接到运行中的 Craft Agent 服务器的终端客户端。可用于脚本编写、CI/CD 流水线、服务器验证，或当你倾向于使用命令行时使用。

安装

# From the monorepo (requires Bun)
bun run apps/cli/src/index.ts --help

# Or add to your PATH
alias craft-cli="bun run $(pwd)/apps/cli/src/index.ts"

连接

CLI 会从标志或环境变量中读取连接详情：

# Via environment (set once)
export CRAFT_SERVER_URL=ws://127.0.0.1:9100
export CRAFT_SERVER_TOKEN=<your-token>

# Or via flags
craft-cli --url ws://127.0.0.1:9100 --token <token> ping

对于 TLS 连接（wss://），若使用自签名证书，请使用 --tls-ca <path>。

命令

命令	描述
ping	验证连接性（clientId + 延迟）
health	检查凭证存储健康状态
versions	显示服务器运行时版本
workspaces	列出工作区
sessions	列出工作区中的会话
connections	列出 LLM 连接
sources	列出已配置的来源
session create	创建会话（--name，--mode）
session messages <id>	打印会话消息历史
session delete <id>	删除会话
send <id> <message>	发送消息并流式传输 AI 响应
cancel <id>	取消进行中的处理
invoke <channel> [args]	使用 JSON 参数进行原始 RPC 调用
listen <channel>	订阅推送事件（按 Ctrl+C 停止）
run <prompt>	独立运行：启动服务器、运行提示词、流式传输响应、退出
--validate-server	21 步集成测试（如果未指定 --url，则自动启动服务器）

Run 命令标志

标志	默认值	描述
--workspace-dir <path>	—	运行前注册工作区目录
--source <slug>	—	启用来源（可重复使用）
--output-format <fmt>	text	输出格式：text 或 stream-json
--mode <mode>	allow-all	会话的权限模式
--no-cleanup	false	退出时跳过会话删除
--server-entry <path>	—	自定义服务器入口点
--provider <name>	anthropic	LLM 提供商（anthropic、openai、google、openrouter、groq、mistral、xai 等）
--model <id>	（提供商默认值）	模型 ID（例如：claude-sonnet-4-5-20250929、gpt-4o、gemini-2.0-flash）
--api-key <key>	—	API 密钥（或 $LLM_API_KEY，或提供商特定的环境变量）
--base-url <url>	—	用于代理或自托管模型的自定义 API 端点

run 命令是完全独立的 — 它会启动一个无头服务器、创建会话、发送提示词、流式传输响应，然后退出。无需单独设置服务器。API 密钥可通过 --api-key、$LLM_API_KEY 或提供商特定的环境变量（例如 $ANTHROPIC_API_KEY、$OPENAI_API_KEY）解析。

示例

# Quick connectivity check
craft-cli ping

# List sessions (human-readable)
craft-cli sessions

# Send a message and stream the AI response
craft-cli send abc-123 "What files are in the current directory?"

# Pipe input
echo "Summarize this" | craft-cli send abc-123

# JSON output for scripting
craft-cli --json workspaces | jq '.[].name'

# Self-contained run (spawns its own server)
craft-cli run "Summarize the README"
craft-cli run --workspace-dir ./my-project --source github "List open PRs"

# Multi-provider support
craft-cli run --provider openai --model gpt-4o "Summarize this repo"
GOOGLE_API_KEY=... craft-cli run --provider google --model gemini-2.0-flash "Hello"
craft-cli run --provider anthropic --base-url https://openrouter.ai/api/v1 --api-key $OR_KEY "Hello"

# Validate the server (auto-spawns if no --url)
craft-cli --validate-server
craft-cli --validate-server --url ws://127.0.0.1:9100 --token <token>

架构

craft-agent/
├── apps/
│   ├── cli/                   # Terminal client (CLI)
│   └── electron/              # Desktop GUI (primary)
│       └── src/
│           ├── main/          # Electron main process
│           ├── preload/       # Context bridge
│           └── renderer/      # React UI (Vite + shadcn)
└── packages/
    ├── core/                  # Shared types
    └── shared/                # Business logic
        └── src/
            ├── agent/         # CraftAgent, permissions
            ├── auth/          # OAuth, tokens
            ├── config/        # Storage, preferences, themes
            ├── credentials/   # AES-256-GCM encrypted storage
            ├── sessions/      # Session persistence
            ├── sources/       # MCP, API, local sources
            └── statuses/      # Dynamic status system

开发

# Hot reload development
bun run electron:dev

# Build and run
bun run electron:start

# Type checking
bun run typecheck:all

# Debug logging (writes to ~/Library/Logs/@craft-agent/electron/)
# Logs are automatically enabled in development

环境变量

OAuth 集成（Slack、Microsoft）需要在构建中嵌入凭据。请创建一个 .env 文件：

MICROSOFT_OAUTH_CLIENT_ID=your-client-id
SLACK_OAUTH_CLIENT_ID=your-slack-client-id
SLACK_OAUTH_CLIENT_SECRET=your-slack-client-secret

注意： 构建中未内置 Google OAuth 凭据。用户需通过源配置自行提供凭据。请参阅下方的 Google OAuth 设置 部分。

Google OAuth 设置（Gmail、日历、云端硬盘、YouTube、Search Console）

Google 集成要求您创建自己的 OAuth 凭据。这是一次性设置。

1. 创建 Google Cloud 项目

1. 访问 Google Cloud 控制台
2. 创建新项目（或选择现有项目）
3. 记录您的项目 ID

2. 启用所需 API

前往 API 和服务 → 库，启用您需要的 API：

• Gmail API - 用于电子邮件集成
• Google Calendar API - 用于日历集成
• Google Drive API - 用于文件存储集成

3. 配置 OAuth 同意屏幕

1. 前往 API 和服务 → OAuth 同意屏幕
2. 选择 外部 用户类型（除非您拥有 Google Workspace）
3. 填写必填字段：
   • 应用名称：例如，"My Craft Agent"
   • 用户支持电子邮件：您的电子邮件
   • 开发者联系信息：您的电子邮件
4. 添加作用域（可选 - 可保留默认值）
5. 将自己添加为测试用户（对于处于测试模式的外部应用是必需的）
6. 完成向导

4. 创建 OAuth 凭据

1. 前往 API 和服务 → 凭据
2. 点击 创建凭据 → OAuth 客户端 ID
3. 应用类型：桌面应用
4. 名称：例如，"Craft Agent Desktop"
5. 点击 创建
6. 记录 客户端 ID 和 客户端密钥

5. 在 Craft Agent 中配置

设置 Google 源（Gmail、日历、云端硬盘、YouTube、Search Console 等）时，将以下字段添加到源的 config.json 中：

{
  "api": {
    "googleService": "gmail",
    "googleOAuthClientId": "your-client-id.apps.googleusercontent.com",
    "googleOAuthClientSecret": "your-client-secret"
  }
}

或者直接告诉智能体您想要连接 Gmail/日历/云端硬盘——它会引导您输入凭据。

安全说明

• 您的 OAuth 凭据与其他源凭据一起加密存储
• 切勿将凭据提交到版本控制
• 对于生产环境使用，请考虑让 Google 验证您的 OAuth 同意屏幕

支持的 LLM 提供商

Craft Agents 支持多种连接 LLM 提供商的方式：

直接连接

提供商	身份验证	说明
Anthropic	API 密钥或 Claude Max/Pro OAuth	通过 Claude Agent SDK 直接连接 Claude
Google AI Studio	API 密钥	内置原生 Google 搜索基础的 Gemini 模型
ChatGPT Plus / Pro	Codex OAuth	使用您的 ChatGPT 订阅登录 — 使用 OpenAI 的 Codex 模型
GitHub Copilot	OAuth（设备代码）	使用您的 Copilot 订阅一键身份验证

第三方和自托管提供商

通过选择自定义端点，可通过 Claude / Anthropic API 密钥 连接支持其他提供商：

提供商	端点	说明
OpenRouter	https://openrouter.ai/api	通过单个 API 密钥访问 Claude、GPT、Llama、Gemini 以及数百种其他模型。使用 provider/model-name 格式（例如 anthropic/claude-opus-4.7）。
Vercel AI Gateway	https://ai-gateway.vercel.sh	通过 Vercel 的 AI 网关路由请求，该网关内置可观测性和缓存功能。
Ollama	http://localhost:11434	在本地运行开源模型。无需 API 密钥。
自定义	任何 URL	任何兼容 OpenAI 或兼容 Anthropic 的端点。

架构

Craft Agents 使用两个智能体后端：

• Claude — 由 Claude Agent SDK 提供支持，该 SDK 原生支持自定义基础 URL 和提供商路由。Anthropic API 密钥、Claude Max/Pro OAuth 以及所有第三方端点均使用此后端。
• Pi — 由 Pi SDK 提供支持，处理 Google AI Studio、ChatGPT Plus（Codex OAuth）、GitHub Copilot OAuth 和 OpenAI API 密钥连接。Pi 连接通过其自身的提供商基础设施进行路由。

配置

配置存储在 ~/.craft-agent/ 目录下：

~/.craft-agent/
├── config.json              # Main config (workspaces, LLM connections)
├── credentials.enc          # Encrypted credentials (AES-256-GCM)
├── preferences.json         # User preferences
├── theme.json               # App-level theme
└── workspaces/
    └── {id}/
        ├── config.json      # Workspace settings
        ├── theme.json       # Workspace theme override
        ├── automations.json  # Event-driven automations
        ├── sessions/        # Session data (JSONL)
        ├── sources/         # Connected sources
        ├── skills/          # Custom skills
        └── statuses/        # Status configuration

自动化

自动化功能可让您在事件发生时触发操作，从而实现工作流程的自动化——例如标签变更、会话开始、工具运行或按 cron 计划执行。

直接告诉智能体即可：

• "设置工作日每天上午 9 点的每日站会简报"
• "当会话被标记为紧急时通知我"
• "跟踪权限模式变更并进行总结"
• "每周五下午 5 点，总结本周已完成的任务"

或者在 ~/.craft-agent/workspaces/{id}/automations.json 中手动配置：

{
  "version": 2,
  "automations": {
    "SchedulerTick": [
      {
        "cron": "0 9 * * 1-5",
        "timezone": "America/New_York",
        "labels": ["Scheduled"],
        "actions": [
          { "type": "prompt", "prompt": "Check @github for new issues assigned to me" }
        ]
      }
    ],
    "LabelAdd": [
      {
        "matcher": "^urgent$",
        "actions": [
          { "type": "prompt", "prompt": "An urgent label was added. Triage the session and summarise what needs attention." }
        ]
      }
    ]
  }
}

提示操作可通过提示创建新的智能体会话。它们支持对来源和技能使用 @提及，并且环境变量（如 $CRAFT_LABEL 和 $CRAFT_SESSION_ID）会自动展开。

支持的事件：LabelAdd、LabelRemove、PermissionModeChange、FlagChange、SessionStatusChange、SchedulerTick、PreToolUse、PostToolUse、SessionStart、SessionEnd 等。

完整参考请参见 自动化文档。

高级功能

大响应处理

超过约 60KB 的工具响应会使用 Claude Haiku 结合意图感知上下文自动进行总结。_intent 字段会注入 MCP 工具模式中，以保持总结的焦点。

深度链接

外部应用可使用 craftagents:// URL 进行导航：

craftagents://allSessions                      # All sessions view
craftagents://allSessions/session/session123   # Specific session
craftagents://settings                         # Settings
craftagents://sources/source/github            # Source info
craftagents://action/new-chat                  # Create new session

技术栈

层级	技术
运行时	Bun
人工智能	@anthropic-ai/claude-agent-sdk
人工智能（Pi）	Pi SDK agent server
桌面端	Electron + React
用户界面	shadcn/ui + Tailwind CSS v4
构建工具	esbuild（主程序） + Vite（渲染进程）
凭证管理	AES-256-GCM 加密文件存储

故障排除

调试模式

要启动打包后的应用并启用详细日志记录，请使用 -- --debug（注意双短横线分隔符）：

macOS：

/Applications/Craft\ Agents.app/Contents/MacOS/Craft\ Agents -- --debug

Windows（PowerShell）：

& "$env:LOCALAPPDATA\Programs\@craft-agentelectron\Craft Agents.exe" -- --debug

Linux：

./craft-agents -- --debug

日志写入位置：

• macOS： ~/Library/Logs/@craft-agent/electron/main.log
• Windows： %APPDATA%\@craft-agent\electron\logs\main.log
• Linux： ~/.config/@craft-agent/electron/logs/main.log

许可协议

本项目基于 Apache License 2.0 许可协议 - 详情参见 LICENSE 文件。

第三方许可

本项目使用 Claude Agent SDK，该 SDK 受 Anthropic 商业服务条款 约束。

商标

"Craft" 和 "Craft Agents" 是 Craft Docs Ltd 的商标。使用指南参见 TRADEMARK.md。

贡献指南

我们欢迎各类贡献！请参见 CONTRIBUTING.md 了解贡献准则。

安全说明

本地 MCP 服务器隔离

在启动本地 MCP 服务器（标准输入输出传输）时，系统会过滤敏感环境变量，以防止凭据泄露给子进程。被阻止的变量包括：

• ANTHROPIC_API_KEY、CLAUDE_CODE_OAUTH_TOKEN（应用授权）
• AWS_ACCESS_KEY_ID、AWS_SECRET_ACCESS_KEY、AWS_SESSION_TOKEN
• GITHUB_TOKEN、GH_TOKEN、OPENAI_API_KEY、GOOGLE_API_KEY、STRIPE_SECRET_KEY、NPM_TOKEN

如需向特定 MCP 服务器显式传递环境变量，请在源配置中使用 env 字段。

如发现安全漏洞，请参见 SECURITY.md 进行报告。