# BlockX 文档

> BlockX 产品与开发者文档。

## Docs

- [欢迎使用 BlockX](https://docs.blockx.chaintable.com/index.md): BlockX 文档中心
- [快速开始](https://docs.blockx.chaintable.com/quickstart.md): 在本机跑通第一个 BlockX task：启动 worker、提交 task、看懂结果
- [架构总览](https://docs.blockx.chaintable.com/architecture/overview.md): BlockX 是什么、由哪些组件构成、一个 task 如何在系统里流动，以及贡献者应该按什么顺序阅读文档。
- [Task 生命周期](https://docs.blockx.chaintable.com/architecture/task-lifecycle.md): 一个 task 从 Client 提交、经 Coordinator 选址、在 Worker 上执行三个阶段到终态可查的端到端主链路
- [协议与接口](https://docs.blockx.chaintable.com/architecture/protocols.md): BlockX 各组件之间用什么协议通信、消息长什么样、改协议时要遵守什么规矩
- [仓库结构与代码分层](https://docs.blockx.chaintable.com/architecture/repository-layout.md): BlockX 仓库里什么放在哪、为什么这么放，以及想改某个功能该去哪个目录
- [设计原则与代码约定](https://docs.blockx.chaintable.com/architecture/design-principles.md): Sans-IO、Scoped Resource Context、Occam's Razor 三条原则如何变成可检查的代码约束，以及 core / adapters / app / api 各层允许做什么。
- [Worker](https://docs.blockx.chaintable.com/components/worker.md): Worker 进程如何管理 task slot、推进 Builder → Calls → Plugin 三个阶段并对外暴露结果
- [Coordinator](https://docs.blockx.chaintable.com/components/coordinator.md): Task Resource Coordinator：基于 etcd 心跳视图为 Client 选址，并向 Worker 预占一个短期 slot
- [Call 执行子系统](https://docs.blockx.chaintable.com/components/call-execution.md): Worker 内把 call list 调度到 Python Executor 池执行的子系统：DispatcherCore、执行 adapter、Executor Pool、子函数调用与 UDS 协议
- [Function Code View](https://docs.blockx.chaintable.com/components/function-code.md): Worker 内的函数代码不可变快照（epoch / digest）、BlockDB 与 Redis syncer，以及派发前的函数代码静态审计
- [IO 访问子系统](https://docs.blockx.chaintable.com/components/io-subsystem.md): Worker 内统一承接 BlockDB / NodeRPC / 能力后端访问的 IO 层：WorkerIOScope、TaskIOScope、缓存、singleflight、自适应准入与 backend adapter 装配
- [Plugin 系统](https://docs.blockx.chaintable.com/components/plugins.md): Call Builder 与 Writer Plugin（ResultHandler）：Task 前后两端的可插拔阶段，如何注册、装配、执行和扩展
- [Python Executor](https://docs.blockx.chaintable.com/components/python-executor.md): 常驻 Python 进程如何装载并执行用户函数、用 greenlet 挂起 IO、通过 UDS 与 Worker 往返，以及用户函数可用的 SDK 与其拦截点。
- [后端适配器](https://docs.blockx.chaintable.com/components/backend-adapter.md): internal/sdk 下的 BlockDB、NodeRPC、logical-types、Iceberg 等后端适配器：如何实现 BackendAdapter 接口、装配进 IO 子系统，以及如何新增一个
- [Sync Invoker](https://docs.blockx.chaintable.com/components/sync-invoker.md): 同步函数调用入口：一次 gRPC unary 请求执行一次 Python 函数并当场返回结果、call_id 与执行归因时长
- [Bundle 集群](https://docs.blockx.chaintable.com/components/bundle.md): bundle coordinator/worker 双入口、bundlescan 流式扫描 parquet 产 call、bundlewrite/tableupserts 经 BlockDB BatchWrite 写回，以及 bundle-loadgen 压测工具
- [可观测性](https://docs.blockx.chaintable.com/components/observability.md): BlockX 的结构化日志、Prometheus 指标、OpenTelemetry tracing、usage 采集与 client id 传播
- [本地开发环境](https://docs.blockx.chaintable.com/development/getting-started.md): 搭建 BlockX 的 Go + Python 开发环境、构建二进制、跑测试，并在本机拉起一个不依赖外部服务的 worker
- [测试](https://docs.blockx.chaintable.com/development/testing.md): BlockX 的测试分层、每一层的命令与前置条件、测试替身、CI 与性能测试入口
- [贡献流程](https://docs.blockx.chaintable.com/development/contributing.md): 向 BlockX 提交改动的工作方式：spec 先行、三条设计原则、代码约定速查、commit 与 PR 规范、AI agent 协作约定。
- [部署概览](https://docs.blockx.chaintable.com/development/deployment.md): BlockX 在生产中的运行形态：有哪些进程、依赖什么、配置怎么发布、镜像怎么构建，以及停机与观测入口在哪。