灵感不过是顽强的劳动而获得的奖赏。——列宾

https://github.com/lukilabs/craft-agents-oss

Craft Agents：一个会“自己把路铺好”的 Agent 桌面工坊

在一个到处都在谈 Agent 的时代，很多工具像是“给你一堆零件，然后祝你好运”。
而 Craft Agents 更像一个穿着工装、背着工具箱、还顺手带着咖啡的队长——你只要说一句“我想做这件事”，它就会开始把路铺平：连 API、连 MCP、搬技能、跑后台任务、开多会话收件箱……而且还很“懂事”，不爱废话。

Craft Agents 是 craft.do 团队为了更高效地和 Agent 协作而打造的工具：它把 直觉化的多任务、与任意 API/服务的无负担连接、会话分享、以及更“Agent Native”的使用方式，揉进了一个能每天用、能长期用、还能随手改的开源项目里。

它同时使用 Claude Agent SDK 与 Pi SDK 两条路线并行：把它们各自擅长的部分留在身上，也把那些“我们一直想改但别处改不了”的地方亲手修整。并且它是 Apache 2.0 开源：你可以自由 remix、修改、换皮、扩展——而且不是“理论上可以”，是真的能改得动。因为他们自己就是用 Craft Agents 来构建 Craft Agents 的。

先看它怎么动起来（视频）

如果你想快速理解 Craft Agents 在干什么、怎么干的，官方给了一个演示视频：

（点图也能看：README 里有 Demo Video 的预览图）

为什么要做 Craft Agents：它不是“又一个聊天框”

Craft Agents 的出发点很直白：

我们想要一个更好的、更加有主张的（最好也别只剩 CLI）方式，去使用世界上最强的 agents。

它带着“Agent Native software principles”的性格：
不要求你先学会一整套配置哲学，也不逼你把所有东西变成 YAML/JSON 仪式。相反，它更像一个真正的“搭档”：

  • 你描述目标
  • 它理解上下文
  • 它把连接、权限、来源、技能、会话状态、后台任务都安排好
  • 你继续推进事情本身

那些“很难相信却真的就能用”的瞬间

Craft Agents 的厉害，不在于它会回答问题，而在于它会把“通路”打通。它的口头禅大概是：“把你要的给我，我来搞定连接。”

1）“我怎么连 Linear、Gmail、Slack……？”

你对它说：

“add Linear as a source.”

它会去找公开 API / MCP servers，读文档、指导你配凭证、把配置接好。
不需要你先开向导，不需要你先写 config 文件。

（README 里还有一个“我刚刚连上 Slack”的分享链接：
https://agents.craft.do/s/DRNQEiy8w2e1v5LPgKl8b ）

2）“我已经有 MCP config JSON 了”

那就直接粘贴。它会把剩下的活接走。

3）“本地 MCP 呢？”

完全支持。stdio 的 MCP server 会作为你机器上的本地子进程跑起来：
你可以指向 npx 命令、Python 脚本或任何本地二进制——它就能工作。

4）“自定义 API 也行吗？”

可以。你可以扔给它 OpenAPI spec、端点 URL、文档截图，甚至“你手头有什么就给什么”。
它会把图拼成路，并一路引导你走。

5）“不止 MCP？还能连 API？”

是的。Craft Agents 说它能连“anything”。README 里直接提到他们把它连到了一个 经 jumpbox 的 Postgres。
它的化学反应公式很简单：

Skills + Sources = magic

6）“我能把 Claude Code 的 skills 和 MCPs 迁过来吗？”

你告诉它要从 Claude Code 导入，它会处理迁移。
README 里也给了“一次性导入所有 skills”的分享链接：
https://agents.craft.do/s/gWCFqwhObFWaNJIEJmd6j

7）“我要新建一个 skill”

你描述 skill 要做什么、给它上下文——它会把 skill 搭起来。

8）“改完要重启吗？”

不需要。即时生效。
你甚至可以在对话中途用 @ 提到新的 skills 或 sources，它会立刻识别并用上。

9）“所以我真的可以就直接问？”

是的。这是它最核心的执念：
你描述你想要的，它负责想办法把“怎么做”落地。这样才是“好好花 tokens”。

安装：一句话把它请进电脑（推荐）

Craft Agents 很干脆，不搞拐弯抹角。

macOS / Linux

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

Windows（PowerShell）

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

从源码构建：亲手把它“养大”

如果你更喜欢自己掌控一切：

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

它都能做什么：把 Agent 的“日常工作台”搭出来

Craft Agents 的特征不是单点功能，而是一整套“能长期使用”的工作流。

  • Multi-Session Inbox：桌面端多会话收件箱，会话管理、状态流转、旗标标记
  • Claude Code Experience：流式响应、工具可视化、实时更新
  • Multiple LLM Connections：可以添加多个 AI Provider，并对 workspace 设置默认
  • Multi-Provider Support：同一套会话机制下，同时支持 Google AI Studio、ChatGPT Plus、GitHub Copilot、OpenAI API keys 与 Anthropic
  • Craft MCP Integration：可用 32+ Craft 文档工具（blocks、collections、search、tasks）
  • Sources：MCP servers、REST APIs（Google/Slack/Microsoft）、本地文件系统都能接
  • Permission Modes：三档权限（Explore / Ask to Edit / Auto），还能自定义规则
  • Background Tasks：长耗时任务后台跑，带进度追踪
  • Dynamic Status System：会话状态（Todo/In Progress/Done…）可自定义
  • Theme System：应用级 + workspace 级层叠主题
  • Multi-File Diff：像 VS Code 一样看一次 turn 的所有文件改动
  • Skills：workspace 内保存的专用 agent 指令集
  • File Attachments：拖拽图片、PDF、Office 文档，自动转换
  • Automations：事件驱动自动化（标签变化、定时、工具使用等触发）

快速开始：让它第一次“上班”

  1. 安装后 启动应用
  2. 选择 API Connection：Anthropic（API key 或 Claude Max）、Google AI Studio、ChatGPT Plus（Codex OAuth）、或 GitHub Copilot OAuth
  3. 创建一个 workspace：用来组织你的 sessions
  4. （可选）连接 sources：MCP servers、REST APIs、本地文件系统
  5. 开始聊天：创建 sessions，和 Claude 交互

桌面端的脾气：它把“会话”当成真正的工作对象

Session Management（会话管理）

  • Inbox/Archive：按工作流状态组织
  • Flagging：重要会话插小旗，随手抓出来
  • Status Workflow：Todo → In Progress → Needs Review → Done
  • Session Naming：AI 自动起名，也能手动改
  • Session Persistence：完整历史保存到磁盘

Sources（来源）

它喜欢“外援”，而且不挑人。

Type Examples
MCP Servers Craft, Linear, GitHub, Notion, custom servers
REST APIs Google (Gmail, Calendar, Drive, YouTube, Search Console), Slack, Microsoft
Local Files Filesystem, Obsidian vaults, Git repos

Permission Modes（权限模式）

它很清楚：Agent 能力越强，越要把“手刹”做得顺手。

Mode Display Behavior
safe Explore 只读，阻止所有写操作
ask Ask to Edit 需要你批准（默认）
allow-all Auto 自动批准所有命令

并且你可以在聊天界面用 SHIFT+TAB 轮换模式。

Keyboard Shortcuts（快捷键）

Shortcut Action
Cmd+N 新对话
Cmd+1/2/3 聚焦 sidebar/list/chat
Cmd+/ 快捷键面板
SHIFT+TAB 切换权限模式
Enter 发送
Shift+Enter 换行

远程 Headless Server：让它去 VPS 上“值夜班”

Craft Agents 可以作为 headless server 跑在远程机器上（比如 Linux VPS），桌面端作为 thin client 连接。这样长时间运行的 sessions 不会因为你合上电脑就断掉，你也能跨设备访问。

Quick Start（从 monorepo 根目录）

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

启动时它会打印类似：

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

你把这俩值复制出来，用桌面端去连即可。

连接桌面端（thin-client 模式）

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

thin-client 模式下：
UI 在桌面端渲染，但会话逻辑、工具执行、LLM 调用都在远程 server 上跑。

环境变量一览

Variable Required Default Description
CRAFT_SERVER_TOKEN Yes — Bearer token，用于 client 身份验证
CRAFT_RPC_HOST No 127.0.0.1 绑定地址（远程访问用 0.0.0.0）
CRAFT_RPC_PORT No 9100 端口
CRAFT_RPC_TLS_CERT No — PEM cert 路径（启用 wss://）
CRAFT_RPC_TLS_KEY No — PEM private key（配 cert 必需）
CRAFT_RPC_TLS_CA No — PEM CA chain（可选，用于 client cert 校验）
CRAFT_DEBUG No false debug 日志

TLS（推荐）

开发/测试自签证书：

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

用 TLS 启动 server：

1
2
3
4
5
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

Docker

1
2
3
4
5
6
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

TLS + Docker（挂载证书）：

1
2
3
4
5
6
7
8
9
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 Client：它也愿意穿上“终端外套”陪你跑脚本

Craft Agents 还有一个 terminal client：它通过 WebSocket（ws:// 或 wss://）连接 Craft Agent server。适合脚本化、CI/CD、server 校验，或者你单纯喜欢命令行的手感。

安装/使用（从 monorepo，需要 Bun）

1
2
3
4
5
# 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 支持 env 或 flags：

1
2
3
4
5
6
# 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>。

支持的命令（节选但不省略原表）

Command Description
ping Verify connectivity (clientId + latency)
health Check credential store health
versions Show server runtime versions
workspaces List workspaces
sessions List sessions in workspace
connections List LLM connections
sources List configured sources
session create Create a session (--name, --mode)
session messages <id> Print session message history
session delete <id> Delete a session
send <id> <message> Send message and stream AI response
cancel <id> Cancel in-progress processing
invoke <channel> [args] Raw RPC call with JSON args
listen <channel> Subscribe to push events (Ctrl+C to stop)
run <prompt> Self-contained: spawn server, run prompt, stream response, exit
--validate-server 21-step integration test (auto-spawns server if no --url)

run 命令 flags

Flag Default Description
--workspace-dir <path> — Register a workspace directory before running
--source <slug> — Enable a source (repeatable)
--output-format <fmt> text Output format: text or stream-json
--mode <mode> allow-all Permission mode for the session
--no-cleanup false Skip session deletion on exit
--server-entry <path> — Custom server entry point
--provider <name> anthropic LLM provider (anthropic, openai, google, openrouter, groq, mistral, xai, etc.)
--model <id> (provider default) Model ID (e.g., claude-sonnet-4-5-20250929, gpt-4o, gemini-2.0-flash)
--api-key <key> — API key (or $LLM_API_KEY, or provider-specific env var)
--base-url <url> — Custom API endpoint for proxies or self-hosted models

CLI 示例：让它在终端里跑起来

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
# 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>

架构：它的骨架长这样（monorepo）

Craft Agents 把桌面端、CLI、核心类型与共享业务逻辑分层摆好，像一个把工具按抽屉分好、贴好标签的工坊：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
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

开发：让它在你的机器上“边跑边长”

1
2
3
4
5
6
7
8
9
10
11
# 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）

这些需要在构建时 baked into build，所以要 .env：

1
2
3
MICROSOFT_OAUTH_CLIENT_ID=your-client-id
SLACK_OAUTH_CLIENT_ID=your-slack-client-id
SLACK_OAUTH_CLIENT_SECRET=your-slack-client-secret

README 也说明：Google OAuth 凭证不是 baked into build，用户会在 source 配置时提供。

Google OAuth Setup：它想连 Gmail/Calendar/Drive 时，会带你走这条路

Craft Agents 对 Google integrations 的态度像个谨慎的管家：钥匙要你自己配好，它负责帮你放进保险箱（加密存储），并提醒你别把钥匙写进仓库。

核心步骤（原 README 结构）：

  1. 创建 Google Cloud Project（记下 Project ID）
  2. 在 APIs & Services 启用需要的 API：Gmail / Calendar / Drive
  3. 配 OAuth consent screen（External；填写必填项；把自己加为 test user）
  4. 创建 OAuth Client ID（Desktop app），记录 Client ID 与 Client Secret
  5. 在 Craft Agent 的 source config.json 中填入：
1
2
3
4
5
6
7
{
  "api": {
    "googleService": "gmail",
    "googleOAuthClientId": "your-client-id.apps.googleusercontent.com",
    "googleOAuthClientSecret": "your-client-secret"
  }
}

也可以直接对它说要连接 Gmail/Calendar/Drive，它会引导你把凭证填进去。

支持的 LLM Providers：它的“朋友圈”不止一家

Craft Agents 支持多种连接方式。

Direct Connections

Provider Auth Notes
Anthropic API key 或 Claude Max/Pro OAuth 通过 Claude Agent SDK 直连 Claude
Google AI Studio API key Gemini 模型，内置 Google Search grounding
ChatGPT Plus / Pro Codex OAuth 用你的 ChatGPT 订阅登录，使用 OpenAI Codex 模型
GitHub Copilot OAuth (device code) 一键用 Copilot 订阅认证

Third-Party & Self-Hosted Providers（通过自定义 endpoint）

Provider Endpoint Notes
OpenRouter https://openrouter.ai/api 单 key 访问多模型，用 provider/model-name 格式
Vercel AI Gateway https://ai-gateway.vercel.sh 带可观测性与缓存
Ollama http://localhost:11434 本地跑开源模型，无需 API key
Custom Any URL 任意 OpenAI-compatible 或 Anthropic-compatible endpoint

双后端结构

  • Claude：Claude Agent SDK（支持自定义 base URL 与 provider routing）
  • Pi：Pi SDK（处理 Google AI Studio、ChatGPT Plus/Codex OAuth、GitHub Copilot OAuth、OpenAI API key 连接等）

配置存放在哪：它的“家”在 ~/.craft-agent/

Craft Agents 把配置与数据落盘，并把凭证加密保存（AES-256-GCM）。它像个把文件归档到抽屉里的人：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
~/.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

Automations：它会自己盯着“事件”��然后拉起新的会话去干活

Craft Agents 的自动化像个小助理：你给它一条规则，它会在对应事件发生时，自觉去开一个 session 执行 prompt。

你可以直接对它说：

  • “Set up a daily standup briefing every weekday at 9am”
  • “Notify me when a session is labelled urgent”
  • “Track permission mode changes and summarise them”
  • “Every Friday at 5pm, summarise this week’s completed tasks”

或者手动写到 ~/.craft-agent/workspaces/{id}/automations.json：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
{
  "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." }
        ]
      }
    ]
  }
}

README 也提到：Prompt actions 支持 @mentions（sources 与 skills），并且会自动展开 $CRAFT_LABEL、$CRAFT_SESSION_ID 等环境变量。
支持的事件包括：LabelAdd, LabelRemove, PermissionModeChange, FlagChange, SessionStatusChange, SchedulerTick, PreToolUse, PostToolUse, SessionStart, SessionEnd 等等。
完整参考： https://agents.craft.do/docs/automations/overview

Advanced Features：它在你看不见的地方也很“会照顾人”

Large Response Handling

当 tool responses 超过 ~60KB，会自动用 Claude Haiku 做总结，并且注入 _intent 字段到 MCP tool schema，用来保留总结焦点。

Deep Linking

它还会“认路”，支持 craftagents:// 深链：

1
2
3
4
5
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

Tech Stack：它用的材料很现代，也很实用

Layer Technology
Runtime Bun
AI @anthropic-ai/claude-agent-sdk
AI (Pi) Pi SDK agent server
Desktop Electron + React
UI shadcn/ui + Tailwind CSS v4
Build esbuild (main) + Vite (renderer)
Credentials AES-256-GCM encrypted file storage

Troubleshooting：它生病时怎么看日志

打包后的 app 想开 verbose logging，用 -- --debug（注意双 dash）：

macOS

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

Windows（PowerShell）

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

Linux

1
./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

License / Trademark / Contributing / Security：它的规矩都写在桌面上

  • License：Apache License 2.0（见 LICENSE）
  • Third-Party Licenses：使用 Claude Agent SDK（受 Anthropic Commercial Terms 约束，README 有链接）
  • Trademark：“Craft” 与 “Craft Agents” 是 Craft Docs Ltd. 的商标（见 TRADEMARK.md）
  • Contributing：欢迎贡献（见 CONTRIBUTING.md���
  • Security：见 SECURITY.md

并且在安全上，它对本地 MCP server 隔离做了明确防护：当它用 stdio transport 启动本地 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 server 明确传 env，可以在 source config 里使用 env 字段。

结尾：它不是“替你思考”，而是“替你接通世界”

Craft Agents 的人格很鲜明：
它不想把你变成“配置工程师”，也不想把你困在单线程的聊天里。它更像一个能开多条战线、能守住权限边界、能拉起 sources 与 skills 的“项目助理 + 连接工程师 + 会话管家”。

你只要开口，它就会说：
“好的，我去把线都接上。你继续往前走。”