lukilabs/craft-agents-oss
GitHub: lukilabs/craft-agents-oss
一个以 Electron 为桌面端、Bun 为运行时的智能体协作平台，解决如何便捷连接多数据源并编排自动化工作流的问题。
Stars: 4183 | Forks: 622
# Craft Agents
[](LICENSE)
[](CODE_OF_CONDUCT.md)
## 工作原理（视频）
要了解 Craft Agents 的作用和工作方式，请观看此视频。
[](https://www.youtube.com/watch?v=xQouiAIilvU)
[点击此处（点击上方图像）在 YouTube 上观看视频 →](https://www.youtube.com/watch?v=xQouiAIilvU)
## 为何构建 Craft Agents
Craft Agents 是一个工具，我们构建它是为了让我们（在 craft.do）能够高效地与智能体协作。它实现了直观的 multitask、无花哨的 API 或服务连接、共享会话，以及更加以文档（而非代码）为中心的工作流程——在美观且流畅的 UI 中完成。
它同时使用了 Claude Agent SDK 和 Pi SDK——在保留我们认为优秀之处的同时，构建并改进我们期望的改进区域。
它基于 Agent Native 软件原则构建，开箱即用且高度可定制。它是这一类工具中的早期代表。
Craft Agents 在 Apache 2.0 许可证下开源——因此你可以自由地 remix 和修改任何内容。这确实是可行的。我们自己也只用 Craft Agents 来构建 Craft Agents——不需要代码编辑器——因此任何定制化只需一个提示即可完成。
我们构建 Craft Agents 是因为我们希望拥有一种更好、更果断（并且最好是非 CLI 方式）的工作方式，以与世界上最强大的智能体协作。我们将持续基于经验和直觉改进它。
## 难以置信但“开箱即用”的功能
**我如何连接到 Linear、Gmail、Slack...？**
告诉智能体“添加 Linear 作为数据源”。它会查找公共 API 和 MCP 服务器，读取文档，设置凭证并配置一切。不需要配置文件，也不需要设置向导。
[看看我如何刚刚连接到 Slack →](https://agents.craft.do/s/DRNQEiy8w2e1v5LPgKl8b)
**我已经有 MCP 配置 JSON。**
粘贴即可。智能体会处理其余部分。
**本地 MCP 呢？**
完全支持。基于 stdio 的 MCP 服务器会在你的机器上作为本地子进程运行。指向一个 npx 命令、Python 脚本或任何本地二进制文件即可。它就是开箱即用。
**它能处理自定义 API 吗？**
可以。粘贴一份 OpenAPI 规范、一些端点 URL、文档的截图或你拥有的任何内容。它会弄明白并引导你完成其余步骤。
**只是 API 而非 MCP？**
Craft Agents 可以连接到任何内容。我们已经将其连接到位于跳板机后面的直接 Postgres 数据库。技能 + 数据源 = 魔法。
**如何导入我的 Claude Code 技能和 MCP？**
告诉智能体你想从 Claude Code 导入技能。它会处理迁移。
[我一次性导入了所有技能 →](https://agents.craft.do/s/gWCFqwhObFWaNJIEJmd6j)
**如何创建新技能？**
描述该技能应执行的操作并提供上下文。智能体会处理其余部分。
**修改后需要重启吗？**
不需要。一切都是即时的。提及新的技能或数据源时使用 `@`，甚至可以在对话中途进行。
**所以我可以随便问它吗？**
可以。这就是智能体原生软件的核心思想。你描述想要什么，它找出实现方式。这是 token 的高效使用。
## 安装
### 一键安装（推荐）
**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 Code 体验**：流式响应、工具可视化、实时更新
- **多 LLM 连接**：添加多个 AI 提供商并为每个工作区设置默认项
- **多提供商支持**：与 Google AI Studio、ChatGPT Plus、GitHub Copilot 或 Anthropic 一起运行会话，同时使用 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 根目录开始：
```
# 生成令牌并启动服务器
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=
```
复制这些值并用于连接桌面应用。
### 连接桌面应用
通过传递服务器 URL 和令牌，以瘦客户端模式启动 Electron 应用：
```
CRAFT_SERVER_URL=wss://203.0.113.5:9100 CRAFT_SERVER_TOKEN= bun run electron:start
```
在瘦客户端模式下，桌面应用渲染 UI，但所有会话逻辑、工具执行和 LLM 调用都在远程服务器上运行。
### 环境变量
| 变量 | 是否必需 | 默认值 | 描述 |
|------|----------|--------|------|
| `CRAFT_SERVER_TOKEN` | 是 | — | 客户端身份验证的承载令牌 |
| `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
# 创建 certs/cert.pem 和 certs/key.pem（有效期 365 天）
```
**使用 TLS 启动服务器：**
```
CRAFT_SERVER_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://:9100`。
**生产环境**，请使用受信任 CA 签发的证书（例如 Let's Encrypt）或通过反向代理（nginx、Caddy）终止 TLS。
### Docker
```
docker run -d \
-p 9100:9100 \
-e CRAFT_SERVER_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= \
-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 流水线、服务器验证或命令行偏好场景。
### 安装
```
# 从单片仓库（需要 Bun）
bun run apps/cli/src/index.ts --help
# 或添加到你的 PATH
alias craft-cli="bun run $(pwd)/apps/cli/src/index.ts"
```
### 连接
CLI 从标志或环境变量读取连接详情：
```
# 通过环境变量（设置一次）
export CRAFT_SERVER_URL=ws://127.0.0.1:9100
export CRAFT_SERVER_TOKEN=
# 或通过标志
craft-cli --url ws://127.0.0.1:9100 --token ping
```
对于 TLS 连接（`wss://`），请使用 `--tls-ca <路径>` 指定自签名证书。
### 命令
| 命令 | 描述 |
|------|------|
| `ping` | 验证连接（客户端 ID + 延迟） |
| `health` | 检查凭证存储健康状态 |
| `versions` | 显示服务器运行时版本 |
| `workspaces` | 列出工作区 |
| `sessions` | 列出工作区中的会话 |
| `connections` | 列出已配置的 LLM 连接 |
| `sources` | 列出已配置的数据源 |
| `session create` | 创建会话（`--name`、`--mode`） |
| `session messages ` | 打印会话消息历史 |
| `session delete ` | 删除会话 |
| `send ` | 发送消息并流式返回 AI 响应 |
| `cancel ` | 取消正在进行的处理 |
| `invoke [args]` | 使用 JSON 参数进行原始 RPC 调用 |
| `listen ` | 订阅推送事件（Ctrl+C 停止） |
| `run ` | 自包含模式：启动服务器、运行提示、返回响应并退出。不需要单独设置服务器。 |
| `--validate-server` | 21 步集成测试（若未提供 `--url` 则自动启动服务器） |
#### 运行命令标志
| 标志 | 默认值 | 描述 |
|------|--------|------|
| `--workspace-dir <路径>` | — | 在运行前注册工作区目录 |
| `--source ` | — | 启用数据源（可重复） |
| `--output-format <格式>` | `text` | 输出格式：`text` 或 `stream-json` |
| `--mode <模式>` | `allow-all` | 会话的权限模式 |
| `--no-cleanup` | `false` | 退出时跳过会话删除 |
| `--server-entry <路径>` | — | 自定义服务器入口点 |
| `--provider <名称>` | `anthropic` | LLM 提供商（`anthropic`、`openai`、`google`、`openrouter`、`groq`、`mistral`、`xai` 等） |
| `--model ` | （提供程序默认值） | 模型 ID（例如 `claude-sonnet-4-5-20250929`、`gpt-4o`、`gemini-2.0-flash`） |
| `--api-key <密钥>` | — | API 密钥（或 `$LLM_API_KEY`，或提供程序特定的环境变量） |
| `--base-url ` | — | 用于代理或自托管模型的定制 API 端点 |
`run` 命令是完全自包含的——它会启动一个无头服务器，创建会话，发送提示，流式返回响应，然后退出。无需单独设置服务器。API 密钥会从 `--api-key`、`$LLM_API_KEY` 或提供程序特定的环境变量（例如 `$ANTHROPIC_API_KEY`、`$OPENAI_API_KEY`）中解析。
### 示例
```
# 快速连接检查
craft-cli ping
# 列出会话（人类可读）
craft-cli sessions
# 发送消息并流式传输 AI 响应
craft-cli send abc-123 "What files are in the current directory?"
# 管道输入
echo "Summarize this" | craft-cli send abc-123
# 用于脚本的 JSON 输出
craft-cli --json workspaces | jq '.[].name'
# 自包含运行（会启动自己的服务器）
craft-cli run "Summarize the README"
craft-cli run --workspace-dir ./my-project --source github "List open PRs"
# 多供应商支持
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"
# 验证服务器（如果没有 --url 则自动启动）
craft-cli --validate-server
craft-cli --validate-server --url ws://127.0.0.1:9100 --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
```
## 开发
```
# 热重载开发
bun run electron:dev
# 构建并运行
bun run electron:start
# 类型检查
bun run typecheck:all
# 调试日志（写入 ~/Library/Logs/@craft-agent/electron/）
# 开发过程中日志已自动启用
```
### 环境变量
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 设置（Gmail、Calendar、Drive、YouTube、Search Console）”部分。
### Google OAuth 设置（Gmail、Calendar、Drive、YouTube、Search Console）
Google 集成需要你创建自己的 OAuth 凭据。这是一个一次性设置。
#### 1. 创建 Google Cloud 项目
1. 访问 [Google Cloud 控制台](https://console.cloud.google.com)
2. 创建一个新项目（或选择现有项目）
3. 记下你的项目 ID
#### 2. 启用所需 API
进入 **API 与服务 → 库**，启用你需要的 API：
- **Gmail API** — 用于邮件集成
- **Google Calendar API** — 用于日历集成
- **Google Drive API** — 用于文件存储集成
#### 3. 配置 OAuth 同意屏幕
1. 进入 **API 与服务 → OAuth 同意屏幕**
2. 选择 **外部** 用户类型（除非你拥有 Google Workspace）
3. 填写必要字段：
- 应用名称：例如 “我的 Craft 智能体”
- 用户支持邮箱：你的邮箱
- 开发者联系邮箱：你的邮箱
4. 添加作用域（可选——可保留默认）
5. 将自己添加为测试用户（在测试模式下，外部应用必需）
6. 完成向导
#### 4. 创建 OAuth 凭据
1. 进入 **API 与服务 → 凭据**
2. 点击 **创建凭据 → OAuth 客户端 ID**
3. 应用类型：**桌面应用**
4. 名称：例如 “Craft Agent 桌面”
5. 点击 **创建**
6. 记下 **客户端 ID** 和 **客户端密钥**
#### 5. 在 Craft Agent 中配置
设置 Google 数据源（Gmail、Calendar、Drive、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 密钥 | Gemini 模型内置原生 Google 搜索 |
| **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 及数百种其他模型。格式：`提供商/模型名`（例如 `anthropic/claude-opus-4.7`） |
| **Vercel AI Gateway** | `https://ai-gateway.vercel.sh` | 通过 Vercel 的 AI 网关路由请求，内置可观测性和缓存 |
| **llama** | `http://localhost:11434` | 在本地运行开源模型。无需 API 密钥 |
| **自定义** | 任意 URL | 任何兼容 OpenAI 或 Anthropic 的端点 |
### 架构
Craft Agents 使用两个智能体后端：
- **Claude** — 由 [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-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
```
### 自动化
自动化允许你在事件发生时触发操作——标签更改、会话开始、工具运行或定时调度。
**直接询问智能体：**
- “设置一个工作日每天上午 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` 等。
请参阅 [自动化文档](https://agents.craft.do/docs/automations/overview) 获取完整参考。
## 高级功能
### 大响应处理
超过 ~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](https://bun.sh/) |
| 人工智能 | [@anthropic-ai/claude-agent-sdk](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk) |
| 人工智能（Pi） | Pi SDK 智能体服务器 |
| 桌面 | [Electron](https://www.electronjs.org/) + React |
| UI | [shadcn/ui](https://ui.shadcn.com/) + 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](LICENSE) 文件了解详情。
### 第三方许可证
本项目使用了 [Claude Agent SDK](https://www.npmjs.com/package/@anthropic-ai/claude-agent-sdk)，其受 [Anthropic 商业服务条款](https://www.anthropic.com/legal/commercial-terms) 约束。
### 商标
“Craft”和“Craft Agents”是 Craft Docs Ltd. 的商标。请参阅 [TRADEMARK.md](TRADEMARK.md) 了解使用指南。
## 贡献
我们欢迎贡献！请参阅 [CONTRIBUTING.md](CONTRIBUTING.md) 获取指南。
## 安全
### 本地 MCP 服务器隔离
启动本地 MCP 服务器（stdio 传输）时，会过滤掉敏感环境变量以防止凭据泄露到子进程。屏蔽的变量包括：
- `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](SECURITY.md)。
## 难以置信但“开箱即用”的功能
**我如何连接到 Linear、Gmail、Slack...？**
告诉智能体“添加 Linear 作为数据源”。它会查找公共 API 和 MCP 服务器，读取文档，设置凭证并配置一切。不需要配置文件，也不需要设置向导。
[看看我如何刚刚连接到 Slack →](https://agents.craft.do/s/DRNQEiy8w2e1v5LPgKl8b)
**我已经有 MCP 配置 JSON。**
粘贴即可。智能体会处理其余部分。
**本地 MCP 呢？**
完全支持。基于 stdio 的 MCP 服务器会在你的机器上作为本地子进程运行。指向一个 npx 命令、Python 脚本或任何本地二进制文件即可。它就是开箱即用。
**它能处理自定义 API 吗？**
可以。粘贴一份 OpenAPI 规范、一些端点 URL、文档的截图或你拥有的任何内容。它会弄明白并引导你完成其余步骤。
**只是 API 而非 MCP？**
Craft Agents 可以连接到任何内容。我们已经将其连接到位于跳板机后面的直接 Postgres 数据库。技能 + 数据源 = 魔法。
**如何导入我的 Claude Code 技能和 MCP？**
告诉智能体你想从 Claude Code 导入技能。它会处理迁移。
[我一次性导入了所有技能 →](https://agents.craft.do/s/gWCFqwhObFWaNJIEJmd6j)
**如何创建新技能？**
描述该技能应执行的操作并提供上下文。智能体会处理其余部分。
**修改后需要重启吗？**
不需要。一切都是即时的。提及新的技能或数据源时使用 `@`，甚至可以在对话中途进行。
**所以我可以随便问它吗？**
可以。这就是智能体原生软件的核心思想。你描述想要什么，它找出实现方式。这是 token 的高效使用。
## 安装
### 一键安装（推荐）
**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 Code 体验**：流式响应、工具可视化、实时更新
- **多 LLM 连接**：添加多个 AI 提供商并为每个工作区设置默认项
- **多提供商支持**：与 Google AI Studio、ChatGPT Plus、GitHub Copilot 或 Anthropic 一起运行会话，同时使用 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 根目录开始：
```
# 生成令牌并启动服务器
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=标签：Agent Native, Agent SDK, Apache 2.0, API 连接, Claude Agent SDK, Craft Agents, Gmail 集成, MCP 服务器, Pi SDK, Slack 集成, UI 工作流, 人工智能代理, 会话共享, 凭据管理, 多任务协作, 威胁情报, 开发者工具, 开源, 提示词驱动, 数据管道, 文档中心化, 无代码编辑, 线性集成, 自动化攻击, 自动化配置, 自定义提示, 软件工程, 高效工作流