> ## Documentation Index > Fetch the complete documentation index at: https://docs.blockx.chaintable.com/llms.txt > Use this file to discover all available pages before exploring further. # 仓库结构与代码分层 > BlockX 仓库里什么放在哪、为什么这么放，以及想改某个功能该去哪个目录 BlockX 是一个 Go 单仓（模块名 `github.com/Chaintable/blockx`），`python/` 里放 Python executor、SDK 和审计器。本页帮你在拿到仓库后快速定位代码；系统级职责划分见 [系统架构总览](/architecture/overview)。 ```text theme={null} blockx/ ├── AGENTS.md # 仓库级协作与目录约定（CLAUDE.md 只是指向它的指针） ├── Makefile # proto 生成、fmt/vet、带覆盖率的 go test ├── Dockerfile # 多阶段构建：Go 二进制 + python:3.12 运行时镜像 ├── test.sh # 在 systemd cgroup 约束下跑 e2e/perf ├── analyze_spans.py # 把 Go/Python 导出的 span JSONL 聚合成 trace 树 ├── api/ # 跨模块共享协议定义，只放数据结构与编解码 │ ├── etcd/ # Worker 心跳结构、registry prefix 解析 │ ├── grpc/ # worker / coordinator / bundlecoordinator / syncinvoker 的 .proto 与生成代码 │ └── uds/ # Worker ↔ Python Executor 的 UDS 消息包络与 codec ├── cmd/ # 进程入口，只有 app.Profile 清单和 main │ ├── worker/ # 全量 block worker（含 e2e 进程级测试） │ ├── bundle_worker/ # bundle 池 worker，只注册 bundle 相关 builder/plugin │ ├── coordinator/ # block Coordinator │ ├── bundle_coordinator/ # bundle Coordinator │ ├── syncinvoker/ # 同步调用服务，装配逻辑直接写在本目录 │ ├── perf/ # 对活部署压测的 CLI │ ├── bundle-loadgen/ # 通过 bundle coordinator 提交合成任务的压测 CLI │ └── blockdb_grpc_stub/ # 基准测试用的 BlockDB gRPC 桩服务 ├── internal/ # 实现代码 │ ├── worker/ # Worker：core/（Sans-IO）+ adapters/ + app/ + devstub/ │ ├── coordinator/ # Coordinator：core/ + adapters/ + app/ │ ├── syncinvoker/ # sync-invoker：core/ + adapters/ │ ├── functioncode/ # Function Code View：core/ + adapters/{redis,blockdb} + audit/ │ ├── io/ # IO 访问子系统（scope-oriented）：core/ assembly/ cache/ quota/ sflight/ adaptive/ capabilitywire/ │ ├── plugin/ # Call Builder（callbuilder/）与 Writer Plugin（event/）+ schema/ │ ├── sdk/ # 后端客户端：blockdb / noderpc / meta / logicaltypes / iceberg / router / localtestservice / grpcclient │ ├── duckdb/borrowed/ # DuckDB 原生绑定之上的低分配读取层 │ ├── obs/ # 日志、Prometheus 指标、OpenTelemetry tracing │ ├── usage/ # 用量采集与 Kafka 发布 │ ├── common/ # TaskID/Stage 等共享类型、clientid、argspool、unsafebytes │ └── testutil/ # 进程级测试脚手架：起 etcd/worker/coordinator 子进程 ├── python/ # uv 管理的 Python 工程（pyproject.toml） │ ├── blockx_executor/ # Executor 进程：UDS 会话、greenlet 运行时、SDK bridge │ ├── blockx_sdk/ # 函数代码用的轻量 SDK（db / rpc / sleep / call_subfunc） │ ├── blockx_audit/ # 纯 stdlib 静态审计器与 framed daemon │ └── tests/ # unittest 单测 ├── e2e/ # 跨组件 Go E2E：contract/ system/ perf/ ├── examples/local_test_service/ # 用 blockx-py 向本地 worker 提交 task 的示例 ├── deploy/ # EC2 systemd + nerdctl 部署脚本、env 示例与脚本测试 └── docs/ # deploy.md、capability-backend-guide.md、specs/（设计文档） ``` ## 分层约定 `AGENTS.md` 定义目录骨架，`docs/specs/code-style.md` 把它展开成可检查的实现约束。要点如下： * `cmd/`：只放装配和启动。Worker 与 Coordinator 的入口是一个 `app.Profile` 清单加一行 `app.Run(...)`；`cmd/worker/main.go` 的 `workerProfile()` 列出 `Deployment`、`Service`、`WorkerRegistryPrefix`、`UsageService`、`Builders`、`Plugins`，`cmd/bundle_worker/main.go` 只是换了一份清单并通过 `TuneDefaults` 调默认值。装配顺序、关停顺序、配置解析都在 `internal/worker/app/` 与 `internal/coordinator/app/`，不能按入口复制。 * `internal//core/`：Sans-IO 领域逻辑。状态机、幂等判定、阶段推进、结果收敛都在这里，例如 `internal/worker/core/worker.go` 的 `WorkerCore` 和 `internal/worker/core/dispatcher.go` 的 `DispatcherCore`。 * `internal//adapters/`：transport、存储、时钟、日志、指标等副作用。例如 `internal/worker/adapters/grpc_server.go`、`etcd_publisher.go`、`orchestrator*.go`，以及子包 `internal/worker/adapters/executor/`（UDS 执行器适配器与进程池）。 * `internal//app/`：装配与配置。`internal/worker/app/config.go` 的 `WorkerFullConfig` 是配置真相，`app.go` 按 `Profile` 建 builder/plugin 注册表、IO backend 模块，并串起启动与关停。 * scope-oriented 模块：`internal/io/` 不走事件/命令 core，而是用 `WorkerIOScope`（`internal/io/core/worker_scope.go`）和 `TaskIOScope`（`internal/io/core/task_scope.go`）把 quota、cache、singleflight、cleanup 绑定到作用域生命周期。 * `api/`：跨模块共享的协议结构、消息包络、字段约定。允许无副作用的校验和编解码辅助，不放 handler、存储模型或状态机。 * `python/`：不受 `code-style.md` 直接约束；运行与测试命令见 `python/README.md` 与 `AGENTS.md`。 `code-style.md` §3 与 §5 对三层的依赖规则可以概括为一段话：`core/` 不得引用 gRPC、etcd client、数据库 client、日志实现、指标实现，不自己取时间、生成随机值或启动 goroutine，尽量不接 `context.Context`；取消、超时、TTL 到期都作为显式输入传进来，输出是可枚举的命令、决策结果或状态快照。`adapters/` 拥有全部 IO 与并发，负责把 core 的命令翻译成副作用，并把定时器、执行器、Plugin、IO 回调重新包装成 core 事件。`app/` 与 `cmd/` 只做装配，不加领域判断、准入策略或协议语义分支。adapter 调用 core 时直接依赖具体类型（`WorkerCore`、`CoordinatorCore`），不为 core 额外抽 interface。 ## 模块索引 站内页面链接指向对应组件页；"主要 spec"是 blockx 仓库 `docs/specs/` 下的文件。 ### `cmd/` | 目录 | 用途 | 组件页 | 主要 spec | | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- | -------------------------------------------------------------------------------- | | `cmd/worker/` | 全量 block worker 入口；`Profile` 注册 dbscan/call\_list/bundlescan 与 devstub builder、四个 writer plugin。同目录 `worker_process_*_test.go` 是 Worker 进程级 E2E | [Worker](/components/worker) | `worker.md`、`worker-test-organization.md` | | `cmd/bundle_worker/` | bundle 池 worker 入口；只注册 `BuilderBundleScan`/`BuilderCallList` 与 `PluginBundleWrite`/`PluginTableUpserts`，`TuneDefaults` 打开 stream build | [Bundle 集群](/components/bundle) | `2026-07-21-block-bundle-clusters.md` | | `cmd/coordinator/` | block Coordinator 入口，watch legacy block registry prefix | [Coordinator](/components/coordinator) | `task-resource-coordinator.md` | | `cmd/bundle_coordinator/` | bundle Coordinator 入口，watch legacy 与 prod-default bundle registry prefix | [Bundle 集群](/components/bundle) | `2026-07-23-bundle-coordinator-api.md`、`2026-07-28-registry-prefix-migration.md` | | `cmd/syncinvoker/` | 同步调用服务入口。装配代码（`config.go`、`io.go`、`function_code.go`、`health.go`）直接放在本目录，没有单独的 `app/` 包 | [Sync Invoker](/components/sync-invoker) | `sync-invoker.md` | | `cmd/perf/` | 对活部署做 reserve/submit/poll 压测的 CLI，输出 P50/P90/P99 | [测试](/development/testing) | `perf-methodology.md` | | `cmd/bundle-loadgen/` | 通过 bundle coordinator 提交合成 task，量 bundle worker 吞吐；`cgroup-snapshot.sh` 采 CPU 累计值 | [Bundle 集群](/components/bundle) | `2026-07-30-ec2-worker-profiling.md` | | `cmd/blockdb_grpc_stub/` | 基准专用 BlockDB gRPC 桩服务，带 endpoint 探针 | [后端适配器](/components/backend-adapter) | 见 `cmd/blockdb_grpc_stub/README.md` | ### `internal/` | 目录 | 用途 | 组件页 | 主要 spec | | ------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------- | | `internal/worker/core/` | `WorkerCore`（slot/task 状态机、TTL、结果保留）与 `DispatcherCore`（call 调度、批次提交） | [Worker](/components/worker)、[Call 执行](/components/call-execution) | `worker.md`、`call-execution-subsystem.md` | | `internal/worker/adapters/` | gRPC server、etcd 心跳发布、`Orchestrator` actor（phase 推进、subcall、wedge 检测）、审计门、影子转发、指标 | [Worker](/components/worker) | `worker.md` | | `internal/worker/adapters/executor/` | Python executor 进程池、UDS 收发、bare/sandbox 两种 spawner | [Call 执行](/components/call-execution)、[Python Executor](/components/python-executor) | `worker-executor-connection-and-python-sdk-hook.md`、`executor-sandbox-isolation.md` | | `internal/worker/app/` | `Profile`、`WorkerFullConfig`、`Run`：按 profile 建注册表、装配 IO backend、启动/关停顺序、内存诊断 | [Worker](/components/worker) | `worker.md`、`2026-07-21-block-bundle-clusters.md` | | `internal/worker/devstub/` | dev/e2e 用的 static/payload builder、log/test plugin、stub backend、noop function-code provider | [测试](/development/testing) | `system-e2e-testing.md` | | `internal/coordinator/core/` | `CoordinatorCore`：worker 视图、候选选择、红线与熔断 | [Coordinator](/components/coordinator) | `task-resource-coordinator.md` | | `internal/coordinator/adapters/` | etcd watcher、`CoordinatorServer`/`BundleCoordinatorServer` gRPC、`WorkerRPCClient` | [Coordinator](/components/coordinator) | `task-resource-coordinator.md` | | `internal/coordinator/app/` | `Profile`（`WorkerRegistryPrefixes`）与 `Run` | [Coordinator](/components/coordinator) | `2026-07-28-registry-prefix-migration.md` | | `internal/syncinvoker/core/` | sync-call 状态机、executor registry、准入选择 | [Sync Invoker](/components/sync-invoker) | `sync-invoker.md` | | `internal/syncinvoker/adapters/` | `Service`（Invoke/DebugInvoke/Precheck）、gRPC server、exec adapter | [Sync Invoker](/components/sync-invoker) | `sync-invoker.md`、`sync-invoker-failure-origin.md` | | `internal/functioncode/core/` | `SnapshotStore`、`TaskFunctionView`、源码 digest | [Function Code](/components/function-code) | `function-code-view.md` | | `internal/functioncode/adapters/{redis,blockdb}/` | 从 Redis 快照或 BlockDB scan/subscribe 同步函数代码 | [Function Code](/components/function-code) | `function-code-view.md` | | `internal/functioncode/audit/` | Go 侧审计器：`blockx_audit` daemon 子进程池、digest 缓存、`RejectionError` | [Function Code](/components/function-code) | `function-code-audit-design.md` | | `internal/io/core/` | `WorkerIOScope`/`TaskIOScope`、`model/`（`BackendAdapter`、`BackendKind`、`ReadReq`）、`stats/` | [IO 子系统](/components/io-subsystem) | `io-subsystem.md` | | `internal/io/assembly/` | `assembly.Build`：把 `Module` 清单变成带 adaptive 准入包装的 backend 注册 | [IO 子系统](/components/io-subsystem) | `io-backend-module-design.md`（在 `docs/`） | | `internal/io/{cache,quota,sflight}/` | 有界 LRU cache、channel 信号量、singleflight 表 | [IO 子系统](/components/io-subsystem) | `io-subsystem.md` | | `internal/io/adaptive/` | 传输无关的 AIMD 并发控制与 `observed/` 指标包装 | [IO 子系统](/components/io-subsystem) | `io-subsystem.md` | | `internal/io/capabilitywire/` | 解 gRPC 样式能力后端的二进制请求信封 | [IO 子系统](/components/io-subsystem) | `capability-backend-guide.md`（在 `docs/`） | | `internal/plugin/callbuilder/` | `BuilderRegistry`、`types/`（`CallBuilder` 接口、`Call`、Substrait 风格 `Plan`）、`dbscan/`、`call_list/`、`bundlescan/` | [Plugins](/components/plugins) | `plugin-system.md`、`substrait_ast.md` | | `internal/plugin/event/` | `PluginRegistry`、`types/`（`WriterPlugin`、`TaskIO`）、`blockdbwrite/`、`returnvalue/`、`bundlewrite/`、`tableupserts/`、`batchwrite/` | [Plugins](/components/plugins) | `plugin-system.md`、`2026-07-30-bundle-write-batch-api.md` | | `internal/plugin/schema/` | 通过 IO 读表 schema 的辅助（`ReadColumns`） | [Plugins](/components/plugins) | `plugin-system.md` | | `internal/sdk/blockdb/` | BlockDB gRPC `Adapter`、executor 用的 `BridgeAdapter`、BatchWrite、stub、`proto/` 与 `gen/` | [后端适配器](/components/backend-adapter) | `io-subsystem.md`、`2026-07-23-grpc-client-balancing.md` | | `internal/sdk/noderpc/` | 节点 JSON-RPC 转发、HTTP 分片、语义批处理 | [后端适配器](/components/backend-adapter) | `noderpc-semantic-batching.md`、`2026-08-06-noderpc-binary-sidecar.md` | | `internal/sdk/meta/`、`internal/sdk/logicaltypes/` | meta 服务 HTTP 客户端；`TableMetaService` gRPC 逻辑类型适配器 | [后端适配器](/components/backend-adapter) | `io-subsystem.md` | | `internal/sdk/iceberg/` | 只读 Glue/Iceberg `Planner`，供 bundle scan 解析数据文件 | [后端适配器](/components/backend-adapter) | `2026-07-21-block-bundle-clusters.md` | | `internal/sdk/router/` | 函数发现能力后端（按参数返回匹配的函数名），进程内包装外部模块 `github.com/chaintable/router/go` 的 `Service` | [后端适配器](/components/backend-adapter) | 无独立 spec；接入样式同 `capability-backend-guide.md`（在 `docs/`） | | `internal/sdk/localtestservice/` | 能力后端全链路模板：`proto/`、`service.go`、`adapter.go` | [后端适配器](/components/backend-adapter) | `capability-backend-guide.md`（在 `docs/`） | | `internal/sdk/grpcclient/` | 多连接策略与 protobuf wire 辅助 | [后端适配器](/components/backend-adapter) | `2026-07-23-grpc-client-balancing.md` | | `internal/duckdb/borrowed/` | DuckDB 原生绑定的连接池、中断、零拷贝 chunk 解码；不含 bundle-scan 策略 | [Bundle 集群](/components/bundle) | 见目录内 `README.md` | | `internal/obs/` | `slog` handler 与 ctx 注入、Prometheus 指标（含 IO adaptive、noderpc batch、syncinvoke）、OTel tracing 初始化 | [可观测性](/components/observability) | `logging.md`、`tracing.md`、`blockx-log-types.md` | | `internal/usage/` | 用量聚合与 Kafka sink（`NewKafkaCollector` fail-closed） | [可观测性](/components/observability) | `2026-07-13-blockx-usage-collection.md` | | `internal/common/` | `types/`（`TaskID`、`Stage`、`TaskCtx`）、`clientid/`、`argspool/`、`unsafebytes/` | [设计原则](/architecture/design-principles) | `client-id-propagation.md` | | `internal/testutil/` | 起 etcd/worker/coordinator 子进程、构建二进制缓存、`RunTestMain` | [测试](/development/testing) | `system-e2e-testing.md` | ### `api/`、`python/`、`e2e/` 及其他 | 目录 | 用途 | 组件页 | 主要 spec | | -------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- | ------------------------------------------------------------------- | | `api/grpc/{worker,coordinator,bundlecoordinator,syncinvoker}/` | `.proto` 与生成的 `*pb/`；`make proto` 重新生成 | [协议与接口](/architecture/protocols) | `worker.md`、`task-resource-coordinator.md`、`sync-invoker.md` | | `api/uds/` | `MessageEnvelope` 与各 payload、帧编解码 | [协议与接口](/architecture/protocols) | `worker-executor-connection-and-python-sdk-hook.md` | | `api/etcd/` | `WorkerHeartbeat`、registry prefix 常量与解析 | [协议与接口](/architecture/protocols) | `2026-07-28-registry-prefix-migration.md` | | `python/blockx_executor/` | Executor 进程：`uds_session.py`、`runtime.py`、`sdk_bridge.py`、`blockdb_bridge.py`、`noderpc_bridge.py`、`module_registry.py` | [Python Executor](/components/python-executor) | `python-function-executor.md` | | `python/blockx_sdk/` | 函数代码可 import 的 SDK：`db`、`rpc`、`sleep`、`call_subfunc`、`get_provider` | [Python Executor](/components/python-executor) | `worker-executor-connection-and-python-sdk-hook.md` | | `python/blockx_audit/` | 纯 stdlib 静态审计器与 stdin/stdout framed daemon | [Function Code](/components/function-code) | `function-code-audit-design.md`、`function-code-python-whitelist.md` | | `python/tests/` | `unittest` 单测 | [测试](/development/testing) | `python-test-organization.md` | | `e2e/contract/` | coordinator↔etcd、coordinator↔worker 契约 E2E（slot TTL、超时、重启、failover） | [测试](/development/testing) | `system-e2e-testing.md` | | `e2e/system/` | smoke/routing/recovery/logical\_type 全链路 E2E | [测试](/development/testing) | `system-e2e-testing.md` | | `e2e/perf/` | 按 S0–S5 矩阵组织的性能测试；产物落 `_artifacts/` | [测试](/development/testing) | `perf-methodology.md`、`perf-test-how-to-v2.md` | | `examples/local_test_service/` | `submit.py`/`local_proxy.py`：用 blockx-py 走本地 worker 调 `LocalTestService` | [本地开发](/development/getting-started) | `capability-backend-guide.md`（在 `docs/`） | | `deploy/` | `systemd/` unit、`scripts/` 安装/启动/健康/回收脚本、`env/` 示例、`tests/` bash 测试 | [部署](/development/deployment) | `docs/deploy.md`、`docs/deploy/*.md` | | `docs/` | `deploy.md`、`capability-backend-guide.md`、`io-backend-module-design.md`、`sync-invoker-grafana.md`、`deploy/`、`specs/` | [部署](/development/deployment) | 见下节 | | `Makefile` | `proto`（含 blockdb/meta/localtestservice）、`fmt`、`vet`、`test`（快包一次跑、syncinvoker 逐文件跑） | [本地开发](/development/getting-started) | — | | `Dockerfile` | 编两个 coordinator、两个 worker、syncinvoker，装进 `python:3.12-slim` 运行时 | [部署](/development/deployment) | — | | `test.sh` | `systemd-run --scope` 加 CPUQuota/MemoryMax 后跑 `./e2e/perf/...` | [测试](/development/testing) | `perf-methodology.md` | | `analyze_spans.py` | 聚合 `/tmp/blockx_spans.jsonl` 之类的 span 文件成 trace 树 | [可观测性](/components/observability) | `tracing.md` | 构建单个二进制用 `go build ./cmd/`，`Dockerfile` 和各 `cmd/*/README.md` 用的都是这条命令。 ## docs/specs 索引 `docs/specs/` 放行为语义的设计文档。文件名有两种：无日期前缀的是子系统长期设计（按子系统命名，如 `plugin-system.md`），`YYYY-MM-DD-` 前缀的是某次增量设计或变更方案，日期是方案提出时间，落地后文件留在原处，部分在开头标注状态（如 `2026-07-21-block-bundle-clusters.md` 的"状态：Implemented"）。 必读六篇：`architecture.md`、`worker.md`、`call-execution-subsystem.md`、`io-subsystem.md`、`plugin-system.md`、`code-style.md`。 | 文件 | 主题 | | ------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------- | | `architecture.md` | 系统总览：Coordinator/Worker/Executor 与 `onchain table -> onchain table` 计算模式 | | `worker.md` | Worker：slot/task 状态机、协议、TTL 与结果保留 | | `call-execution-subsystem.md` | Worker 内 call 调度、执行、挂起恢复、子函数调用、代码装载 | | `io-subsystem.md` | IO 访问子系统：scope、quota、cache、singleflight、backend | | `plugin-system.md` | Call Builder 与 Writer Plugin 的接口、数据结构、装配 | | `code-style.md` | `core/adapters/api/scope` 边界与错误、时间语义约束 | | `task-resource-coordinator.md` | Coordinator：worker 视图、候选、红线、熔断 | | `function-code-view.md` | 函数代码快照的来源、发布、pin | | `function-code-audit-design.md` | Function Code 静态审计与执行规则 | | `function-code-python-whitelist.md` | 审计允许的 Python 子集白名单 | | `python-function-executor.md` | Python Executor 内部：greenlet 运行时、SDK 桥接、UDS 事件循环 | | `python-executor-process-metrics.md` | Executor 心跳里进程指标的采样方式 | | `worker-executor-connection-and-python-sdk-hook.md` | Worker↔Executor UDS 连接协议与 SDK hook | | `executor-sandbox-isolation.md` | Executor containerd 沙箱隔离 | | `sync-invoker.md` | 同步调用服务技术方案 | | `sync-invoker-failure-origin.md` | sync-invoker 错误分类 | | `noderpc-semantic-batching.md` | NodeRPC 透明语义批处理 | | `substrait_ast.md` | 行级过滤与去重的 Substrait 风格 `Plan`（`internal/plugin/callbuilder/types/operator.go`） | | `client-id-propagation.md` | client ID 在 gRPC metadata、HTTP header、进程内的传播 | | `logging.md` | 结构化日志契约（Go `slog` 与 Python `logging`） | | `blockx-log-types.md` | 用户视角关键日志类型与检索方式 | | `tracing.md` | OpenTelemetry 链路追踪 | | `system-e2e-testing.md` | 开发机全链路验证设计 | | `worker-test-organization.md` | Worker Go 测试组织标准 | | `python-test-organization.md` | Python 单测组织标准 | | `perf-methodology.md` | 性能排查方法论，`e2e/perf/` 的矩阵依据 | | `perf-test-how-to-v2.md`、`perf-test-report-v2.md`、`perf-test-report.md`、`perf-test-report-appendix.md` | 性能测试复现指引与历史报告 | | `perf-capability-backend-report.md` | 能力后端框架层成本报告 | | 文件 | 主题 | | ---------------------------------------------------- | -------------------------------------------------- | | `2026-07-13-blockx-usage-collection.md` | Worker 用量写 Kafka 的当前实现 | | `2026-07-14-dbscan-in-memory-operator.md` | DBScan 按 table+block 读取，过滤/去重改成内存 operator | | `2026-07-16-task-owner-lease-and-cancellation.md` | 复用 `WatchTasks` 流做 task 断连回收（watch grace） | | `2026-07-21-block-bundle-clusters.md` | block / bundle 两套部署拆分 | | `2026-07-23-bundle-coordinator-api.md` | Bundle Coordinator 独立 gRPC service | | `2026-07-23-execute-call-function-code-reference.md` | ExecuteCall 只带源码 digest，Executor 按需拉源码 | | `2026-07-23-grpc-client-balancing.md` | NLB 后 gRPC 多连接负载均衡（`internal/sdk/grpcclient`） | | `2026-07-28-registry-prefix-migration.md` | Worker etcd registry prefix 兼容迁移 | | `2026-07-30-bundle-write-batch-api.md` | BundleWrite/TableUpserts 改用 BlockDB BatchWrite Job | | `2026-07-30-ec2-worker-profiling.md` | EC2 Worker 无宿主机依赖的 pprof / py-spy 采样 | | `2026-07-30-python-executor-cpu-optimization.md` | Python Executor CPU 优化设计与基线 | | `2026-08-06-noderpc-binary-sidecar.md` | NodeRPC bridge 二进制直通 | ## "我想改 X，该看哪里" | 想改的东西 | 先看这里 | 一起改 / 参考 | | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- | | 新增 Call Builder | `internal/plugin/callbuilder//`，实现 `types.CallBuilder`；在 `internal/plugin/callbuilder/types/types.go` 加 `CallBuilderName` | `internal/worker/app/app.go` 的 `newBuilderRegistry` switch，`cmd/worker/main.go` / `cmd/bundle_worker/main.go` 的 `Builders` 清单；`docs/specs/plugin-system.md` | | 新增 Writer Plugin | `internal/plugin/event//`，实现 `types.WriterPlugin`；在 `internal/plugin/event/types/types.go` 加 `PluginName` | `internal/worker/app/app.go` 的 `newPluginRegistry`，入口 `Plugins` 清单；`docs/specs/plugin-system.md` | | 改 slot / task 状态机、TTL、结果保留 | `internal/worker/core/worker.go`、`worker_slots.go`、`types.go` | 定时器与副作用在 `internal/worker/adapters/orchestrator*.go`；`docs/specs/worker.md` | | 改 call 调度、批次、重试、subcall | `internal/worker/core/dispatcher*.go` | `internal/worker/adapters/orchestrator_dispatch.go`、`orchestrator_subcall.go`；`docs/specs/call-execution-subsystem.md` | | 改 Worker ↔ Executor UDS 消息 | `api/uds/types.go`、`api/uds/codec.go` | `python/blockx_executor/messages.py`、`wire_keys.py`、`uds_codec.py`；`docs/specs/worker-executor-connection-and-python-sdk-hook.md` | | 改 gRPC 协议 | `api/grpc//*.proto`，跑 `make proto` | 对应 adapter：`internal/worker/adapters/grpc_server.go`、`wire.go` 或 `internal/coordinator/adapters/grpc_server.go`；同步更新 spec | | 加 IO / 能力后端 | `internal/sdk//`（`proto/`、`service.go`、`adapter.go`），实现 `iocore.BackendAdapter` | `internal/worker/app/app.go` 的 `backendModules` 加一个 `assembly.Module`；`cmd/syncinvoker/io.go`；`python/blockx_audit/tables.py`；`docs/capability-backend-guide.md` | | 改 IO quota / cache / singleflight 语义 | `internal/io/core/task_scope*.go`、`worker_scope.go` | `internal/io/{cache,quota,sflight}/`；`docs/specs/io-subsystem.md` | | 改后端准入（AIMD）或超时 | `internal/io/adaptive/` | 各 `internal/sdk//adaptive.go`；`WorkerFullConfig` 中对应 AIMD 字段 | | 加指标 / 日志字段 / span | `internal/obs/metrics*.go`、`logger.go`、`tracing.go` | 在对应 adapter 打点；Python 侧 `python/blockx_executor/metrics.py`、`logging_setup.py`、`tracing_setup.py`；`docs/specs/logging.md`、`tracing.md` | | 改 Worker 配置项 | `internal/worker/app/config.go` 的 `WorkerFullConfig` | 入口默认值走 `Profile.TuneDefaults`；`deploy/env/worker.env.example` | | 改 Coordinator 选址 / 红线 / 熔断 | `internal/coordinator/core/coordinator.go`、`worker_view.go` | `internal/coordinator/adapters/etcd_watcher.go`；`docs/specs/task-resource-coordinator.md` | | 改 Function Code View 同步或审计 | `internal/functioncode/core/`、`adapters/{redis,blockdb}/`、`audit/` | 审计规则在 `python/blockx_audit/`；`docs/specs/function-code-view.md`、`function-code-audit-design.md` | | 改 Python 运行时、SDK bridge | `python/blockx_executor/runtime.py`、`sdk_bridge.py`、`context.py` | `python/blockx_sdk/`；`docs/specs/python-function-executor.md` | | 改 bundle 扫描 / DuckDB 读取 | `internal/plugin/callbuilder/bundlescan/` | 通用绑定层 `internal/duckdb/borrowed/`；`internal/sdk/iceberg/` | | 改 sync-invoker | `internal/syncinvoker/core/`、`adapters/service.go`、`cmd/syncinvoker/` | `api/grpc/syncinvoker/sync_invoker.proto`；`docs/specs/sync-invoker.md` | | 改部署 | `deploy/scripts/`、`deploy/systemd/`、`deploy/env/`，跑 `deploy/tests/*.sh` | `Dockerfile`、`.github/workflows/`；`docs/deploy.md`、`docs/deploy/*.md` | | 加 E2E | 单进程：`cmd/worker/worker_process_*_test.go`；跨组件：`e2e/contract/`、`e2e/system/`；性能：`e2e/perf/` | 脚手架 `internal/testutil/`；`docs/specs/system-e2e-testing.md`、`worker-test-organization.md` | ## 相关文档 * blockx 仓库 `AGENTS.md`：目录骨架、命令、提交约定。 * blockx 仓库 `docs/specs/code-style.md`：`core/adapters/api/scope` 的实现约束。 * blockx 仓库 `docs/specs/architecture.md`：系统总览。 * blockx 仓库 `docs/capability-backend-guide.md`：新增能力后端的逐文件操作手册。 * 站内：[系统架构总览](/architecture/overview)、[设计原则与代码约定](/architecture/design-principles)、[协议与接口](/architecture/protocols)、[本地开发环境与构建](/development/getting-started)、[测试组织与命令](/development/testing)、[贡献流程与约定](/development/contributing)。