Crate 结构与仓库布局

适用版本：ChengOS v0.1.0+ ｜ 最后核对：2026-08-12 ｜ 来源：chengflow/Cargo.toml、chengflow/CLAUDE.md、crates/

后端是一个 Cargo workspace。本页就是它的地图：每个 crate 拥有什么，以及初次找东西时最费时间的命名陷阱。

工作空间成员

members = [
  "crates/cheng-vector",   "crates/cheng-common",   "crates/cheng-core",
  "crates/cheng-storage",  "crates/cheng-engine",   "crates/cheng-file-ops",
  "crates/cheng-code-index","crates/cheng-local-executor",
  "crates/cheng-workspace-tools", "crates/cheng-nodes", "crates/cheng-llm",
  "crates/cheng-adapters", "benches/cheng-engine-benchmarks",
  "crates/cheng-api",      "crates/cheng-cli",      "crates/cheng-mcp",
  "crates/chengctl",
]
default-members = ["crates/cheng-api", "crates/chengctl"]

default-members 很重要。 不带参数的 cargo build 或 cargo run 只作用于 cheng-api 和 chengctl。要全部构建用 --workspace，要构建单个用 -p <crate>。

工作空间使用 edition 2024，依赖版本集中钉在 [workspace.dependencies]——当多个 crate 都需要某个依赖时，加在那里，而不是加在成员 crate 里。

各个 crate

基础

cheng-core 是需要守护的那个 crate。如果你要加的东西需要数据库连接、HTTP 客户端或文件系统路径，它就不属于这里。

基础设施

执行

cheng-runtime 不是顶层工作空间成员——它是 cheng-nodes 的路径依赖。在成员列表里找它是找不到的。

cheng-code-index 的核心与存储无关，可选的持久 PostgreSQL 存储和 Redis 协调藏在 cargo feature 后面：redis-state、lang-typescript、lang-javascript、lang-python。Rust 支持是内建的，其他语言由 feature 控制。

共享的「本地执行三件套」

这三个 crate 之所以存在，是因为同一批操作必须在服务端与客户端以完全一致的语义运行：

cheng-file-ops 被 tools/file_ops_hub 的两个后端共享——cheng-nodes 里的服务端本地垫片，以及客户端本地执行器。cheng-local-executor 被每一个本地客户端复用：cheng CLI、它的 TUI 与 headless 外壳，以及桌面客户端。这正是要点所在：文件语义不能在「服务器做的」和「你机器做的」之间发生漂移。

接口

cheng-cli 的 lib.rs 暴露了 API 客户端、事件流和会话缓存，以便集成测试驱动它们；main.rs 只是在其上的薄组装层。二进制名叫 cheng，不叫 cheng-cli。

宏

cheng-macros 是 crate 的目录名，但 Cargo 包名是 cheng-workflow-macros，Rust 导入路径是 cheng_workflow_macros。它提供 #[derive(Node)] 和 #[derive(FieldOrder)]。

这是最耗时间的命名陷阱。use cheng_macros::Node; 编译不过。

chengflow/ 下的非 Rust 目录

node_skills/ 和 skills/ 是面向 LLM 的资产，不是 Rust 代码。新增一个节点通常也意味着要加一个 node_skills/<node>/ 条目，否则智能体不知道怎么用它。

节点实现目录

在 cheng-nodes/src/nodes/builtin/ 之下：

agent  ai  chat  document  io  rag  table  tools  translation  ui  utils  workspace

#[node(...)] 宏里的 category 值——trigger、control、webui 等——是给界面用的逻辑分组，可能与目录名不同。不要以为 category = "Utils" 就代表文件在 utils/ 里，反之亦然。

找路

文档与打包

Makefile 从代码生成 API 文档——make openapi、make docs、make dev、make test-api；完整列表用 make help。./build.sh 构建发行二进制并打包 Docker 与 hybrid 产物，默认单用户模式与 x86_64-unknown-linux-musl 目标。

下一步

• 架构详解——这些 crate 之间的关系。
• 自定义节点开发——在 cheng-nodes 里动手。
• 开发环境搭建——先把构建跑起来。