SinkSINK Project
Tutorials

快速开始

初始化 Sink 并运行第一个 AI 任务

本教程将引导你完成首次使用 Sink 的完整流程：初始化配置、启动 Web UI、创建并运行第一个 AI 任务。

前置条件

  • sink 二进制文件已在 PATH 中（由发行版提供）
  • 至少安装了一个支持的 Agent Runtime（参见下方 Runtime 要求）

Runtime 要求

每个 Builtin Runtime 有特定的前提条件：

Runtime要求安装提示
Claude Codeclaude >= 2.1.0 + claude-agent-acphttps://code.claude.com/docs/en/quickstart#step-1-install-claude-code
Codexcodex >= 0.125.0 + codex-acphttps://developers.openai.com/codex/cli#cli-setup
Factory Droiddroid >= 0.114.0https://docs.factory.ai/cli/getting-started/quickstart#step-1-install-and-start-droid
OpenCodeopencode >= 1.14.0https://opencode.ai/docs/install

步骤 1：初始化配置

运行初始化命令：

sink init

init 会按以下流程交互执行：

1. 检测已安装的 Runtime

◆ Sink Init
⠋ Detecting installed agent runtimes...
✔ Detected 2 available runtime(s)

系统扫描本地已安装的 Builtin Runtime（Claude Code、Codex、Factory Droid、OpenCode）。如果未找到支持的 Runtime，命令会打印安装说明并退出。

2. 选择默认 Profile 的 Runtime

系统展示可用的 Runtime 及版本提示，用方向键选择后按 Enter：

◆ Select runtime for the default profile
│  ● claude-code   Claude Code (3.2.0 + claude-agent-acp)
│  ○ codex         OpenAI Codex (0.130.0 + codex-acp)
│  ○ factory-droid Factory Droid (0.120.0)
│  ○ opencode     OpenCode (1.14.0)
└

不可用的 Runtime 会显示为禁用状态，并附带原因（如 “not found” 或 “outdated”）。

3. 探测 Runtime 并配置默认 Profile

系统通过 ACP 探测选中的 Runtime，发现可用配置选项（model、mode 等），然后提示你配置默认 Profile：

◆ Profile name
│  Default Profile (Claude Code)
◆ Default model
│  ● sonnet[1m]
│  ○ opus
│  ○ haiku
◆ Profile description
│  Generic agent using Claude Code
◆ System prompt / instructions (optional)
│

你可以选择创建额外的 Profile，使用不同的 Runtime。

4. 审查并确认

系统显示所有待写入文件的 diff 预览：

── Write Plan ─────────────────────────────────────────
runtimes.json (create)
  + {"agentRuntimes":{"claude-code":{...}}}
settings.json (create)
  + {"env":{},"logLevel":"info"}
gateway.json (create)
  + {"port":5000,"logLevel":"info","authTokens":[]}
mcp.json (create)
  + {"mcpServers":{}}
profiles/default.md (create)
  + ---
  + name: default
  ...
skills/ (create directory)
────────────────────────────────────────────────────────
◆ Proceed with write? (Y/n)

5. 可选：从 Marketplace 安装

如果配置了默认 marketplace，系统会提示安装推荐资源：

◆ Install recommended resources from default marketplace [cclab/marketplace]? (Y/n)

完成后：

✔ Sink is ready

步骤 2：确认默认 Profile

init 完成后，检查默认 Profile：

cat ~/sink/profiles/default.md

内容将类似如下（具体的 configDefaults 取决于 Runtime 的 ACP 探测结果）：

---
name: default
description: Generic agent using Claude Code
runtime: claude-code
configDefaults:
  model:
    type: string
    value: sonnet[1m]
    candidates:
      - opus
      - sonnet[1m]
      - haiku
---

如需调整，直接编辑此文件。runtime 值必须与 runtimes.json 中的某个 Runtime ID 一致。

步骤 3：启动 Gateway

sink gateway start

启动成功后，你将看到类似如下的 JSON 日志输出：

{"level":30,...,"mode":"release","version":"...","msg":"Gateway starting"}
{"level":30,...,"workspaceId":"default","msg":"WorkspaceProxy connected to WorkspaceHost"}
{"level":30,...,"workspaceId":"default","transport":"local","msg":"WorkspaceProxy connected"}
{"level":30,...,"msg":"GatewayWorkspaceManager started: 1 workspaces"}
{"level":30,...,"msg":"Boot checks passed"}
{"level":30,...,"msg":"Gateway listening on port 5000"}

Boot checks passed 表示配置验证通过。若此行缺失并显示 fatal 错误，说明配置存在问题（见常见问题）。

默认监听 127.0.0.1:5000。如需指定端口或地址：

sink gateway start --port 8080 --host 0.0.0.0

步骤 4：访问 Web UI

打开浏览器访问：

http://127.0.0.1:5000

你将看到 Sink Web UI 主界面，左侧是导航栏，中央是工作区。

步骤 5：创建并运行第一个任务

  1. 在顶部工具栏点击 “New Task”
  2. 输入任务描述（例如：分析这段 Python 代码中的安全问题）
  3. Profile 下拉菜单选择 “Default”
  4. 点击 “Create” 创建任务

任务创建后，界面跳转至任务视图，状态从 created → routing → generating → running。

在底部输入框中发送第一条消息给 Agent：

Hello, please introduce yourself and explain what you can help me with.

按 Enter 发送。Agent 开始流式输出响应，你可以实时看到其思考过程。

若 Agent 需要执行操作（如运行命令或写文件），会弹出权限审批提示，点击 “Approve” 或 “Deny”。

常见问题

fatal: No runtimes configured

runtimes.json 为空或不存在。运行 sink init 检测并配置 Runtime。确保至少安装了一个 Runtime（Claude Code、Codex、Factory Droid 或 OpenCode）。

fatal: No default profile found

profiles/default.md 不存在。运行 sink init 创建，或参考步骤 2 手动创建。

fatal: Default profile references unknown runtime '...'

profiles/default.md 中的 runtime 字段值与 runtimes.json 中的 ID 不匹配。检查两边的 ID 是否一致：

cat ~/sink/runtimes.json | head -10
cat ~/sink/profiles/default.md | head -8

Agent 无响应

检查所选 Runtime 是否正确安装并可执行。运行 sink init——它会探测 Runtime 并报告任何问题（版本过旧、缺少配套工具等）。

下一步

产品概述

Sink 是什么、解决什么问题、核心概念和典型使用场景

Canvas 工作区

使用 Canvas 画板进行可视化的多任务管理