快速开始

这一页是一条不分叉的最短路径：从克隆仓库到看见第一个 task 的返回值，全程不依赖 etcd、BlockDB、Meta 或链节点。跑完之后你会对照架构文档知道刚才发生了什么。想先建立整体印象，看架构总览；需要完整的依赖表、Makefile 目标和环境变量清单，看本地开发环境。

前置

Go（go.mod 声明 go 1.26.4）和可用的 C 编译器 —— cmd/worker 链接 DuckDB，必须开 CGO
Python ≥ 3.12 与 uv
能通过 git 访问 github.com/Chaintable/* 私有仓库（Go 与 Python 依赖都有私有包）

五步跑通

克隆并装依赖

git clone git@github.com:Chaintable/blockx.git
cd blockx
go mod download
uv sync --project python

第二条命令在 python/.venv/ 建出 executor 用的 venv，下一步的 PYTHON_BIN 要指向它。

编译 worker

go build -o /tmp/blockx-worker ./cmd/worker

首次编译要链接 DuckDB 静态库，比其他包慢；之后走构建缓存。

启动 worker

WORKER_LISTEN=127.0.0.1:9221 \
WORKER_ADDR=127.0.0.1:9221 \
EXECUTOR_COUNT=1 \
PYTHON_BIN=$PWD/python/.venv/bin/python \
PYTHONPATH=$PWD/python \
ETCD_ENDPOINTS=none \
ICEBERG_NAMESPACE=chaintable_test \
BLOCKX_USAGE_DISABLED=true \
BLOCKDB_BATCH_WRITE_ADDR=127.0.0.1:1 \
STUB_BLOCKDB_DELAY_MS=0 \
/tmp/blockx-worker

日志出现 worker listening 和 executor started 就绪。这十项都是必需的：少了 ICEBERG_NAMESPACE 或 BLOCKDB_BATCH_WRITE_ADDR，进程在配置校验阶段直接退出（WorkerFullConfig.Validate 与 validateProfileRuntimeConfig）。ETCD_ENDPOINTS=none 表示不注册到 etcd，也就没有 Coordinator 参与；BLOCKDB_BATCH_WRITE_ADDR 填一个不可达端口即可，STUB_BLOCKDB_DELAY_MS=0 把读路径切回 devstub。

启动本地 proxy（另开一个终端）

cd examples/local_test_service
uv sync
uv run python local_proxy.py

blockx-py 只通过 PROXY_SOCKET_PATH 指定的 UDS proxy 连接（线上那一环是 notebook 执行引擎的组件，不随本仓库发布），local_proxy.py 在本地补上它：把 WorkerService 的四个 RPC 字节级转发给 worker，并把两套 coordinator 的 ReserveWorkerSlot 垫成对 worker 自己的 RequestTaskSlot。输出 [proxy] listening on unix:/tmp/blockx-proxy.sock -> worker 127.0.0.1:9221 即就绪。

提交 task

uv run python submit.py

[{'message': 'hello, ct2'}, {'message': 'hello, blockx'}]

结果按各次调用的完成序收集，不保证与 callList 的行序一致 —— 多次调用在 executor 内并发执行。需要结果与入参的对应关系时，让返回值自己带上入参，本例的 message 里就带着 name。

你刚才提交了什么

submit.py 的核心是一段 function code 加一份 call 配置：

source_code = """
from blockx import LocalTestService

def _(name):
    return {"message": LocalTestService().helloworld(name)}
"""

task = TaskBuilder.build(
    CallListCallConfig(
        func=Function(source_code=source_code),
        callList=[["ct2"], ["blockx"]],
    ),
    ReturnValueResultHandler(),
)
result = task.submit(timeout=30)

三个要点：

入口函数名必须是 _，每次调用拿到 callList 的一行作为位置参数。两行就是两次调用。
CallListCallConfig 是 Builder，决定这个 task 展开成哪些 call；ReturnValueResultHandler 是 Plugin，决定结果怎么收口。
LocalTestService 是 worker 内置的示例能力后端。function code 里它是个普通 gRPC client，executor 启动时把 channel 换成 BridgeChannel，调用被截回 worker 进程内分派 —— 这就是接入新能力后端的范式，见后端适配器。

结果里能看到什么

worker 的 task_finished 日志把这次执行拆成了三个阶段：

{"msg":"task finished","state":"SUCCEEDED","task_duration_ms":14,"output_count":2,
 "phases":[{"phase":"builder","status":"success","call_count":2},
           {"phase":"calls","status":"success","call_count":2},
           {"phase":"writer","status":"success","plugin_name":"ReturnValueResultHandler"}],
 "io_backends":[{"backend":"localtestservice",
                 "operation":"/localtestservice.v1.LocalTestService/HelloWorld","ops_success":2}]}

builder → calls → writer 就是 Worker 的三阶段状态机：Builder 把配置展开成 call 列表，Calls 阶段在 executor 里并发跑 function code，Writer 阶段交给 Plugin 收口。io_backends 记录了这次 task 打到的能力后端与调用次数。展开讲在 Task 生命周期。

不想起 proxy，也可以直接跑一条 process E2E 看真实调用链： go test -v -timeout 300s ./cmd/worker/ -run TestWorkerProcess_RequestSlotAndSubmit

卡住了

现象	原因
worker 启动即退出，`invalid worker runtime config`	按错误串补变量：`icebergNamespace must not be empty` 补 `ICEBERG_NAMESPACE`；`requires blockdb.batchWriteAddr` 补 `BLOCKDB_BATCH_WRITE_ADDR`
`build constraints exclude all Go files in duckdb-go-bindings/lib`	`CGO_ENABLED=0` 的症状。worker 必须开 CGO 并有 C 编译器
executor 反复重启	`PYTHON_BIN` 没指向 `python/.venv/bin/python`，或漏了在仓库根 `uv sync --project python`
`PROXY_SOCKET_PATH not set` / `UNAVAILABLE`	proxy 没起，或 socket 路径与 `submit.py` 不一致（默认都是 `/tmp/blockx-proxy.sock`）
task 失败且 `failure_code` 为 `CALL_FAILED`	function code 内部抛异常。若启动时设了 `LOCAL_TEST_SERVICE_DISABLED=true`，worker 日志里会是 `no adapter registered for backend: localtestservice`
`go mod download` 拉不到 `github.com/Chaintable/*`	私有模块。配好 git 凭据并设 `GOPRIVATE=github.com/Chaintable/*`

更多问题见本地开发环境的常见问题一节。

下一步

架构总览

组件构成、核心约束与建议阅读顺序。

Task 生命周期

刚才那个 task 在系统里的完整时序。

本地开发环境

完整依赖表、Makefile 目标与环境变量清单。

贡献流程

改代码之前先读这页。

开始使用

架构

组件

开发指南

前置

五步跑通

你刚才提交了什么

结果里能看到什么

卡住了

下一步

架构总览

Task 生命周期

本地开发环境

贡献流程

​前置

​五步跑通

​你刚才提交了什么

​结果里能看到什么

​卡住了

​下一步

架构总览

Task 生命周期

本地开发环境

贡献流程

前置

五步跑通

你刚才提交了什么

结果里能看到什么

卡住了

下一步