开发环境搭建

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

本页面向想构建 ChengOS 本身的人。如果你只是想运行它，请看安装 ChengOS——整机安装走 deploy/chengos.sh，而不是这里的命令。

仓库布局

chengos 是一个元工作空间，不是单一仓库。在你第一次敲 git status 之前，有个坑值得先知道。

产品名与目录名并不一致。 渠道网关在文档和部署配置里叫 chengflow-app，但代码在 chengflow-sdk/。

Git 拓扑

chengflow/、chengflow-ui/、chengapp/ 和 chengflow-sdk/ 是各自独立的仓库，各有自己的 .git。根 .gitignore 忽略了前三个，因此它们的源码不会被上传到公开镜像。chengflow-sdk/ 被记录为一个没有 .gitmodules 的裸 gitlink，所以只要它的工作树移动，根目录 git status 就会显示 m chengflow-sdk——这是预期行为，不是工作树变脏。

根目录的 git status 和 git diff 不会显示任何子项目内部的文件级改动。要进到子项目里运行 git：

cd chengflow && git status --short && git diff

根仓库并不空：它拥有 deploy/、scripts/、.github/ 以及发行元数据（VERSION、CHANGELOG.md、README.md、release.sh）。

一处横切改动——比如某个节点的 schema——意味着既要改 chengflow/ 里的 Rust，也要改某个前端里对应的处理，并在每个受影响的仓库分别提交。

还有三个相关项目根本不在这棵树里。chenghub、skill-registry 和 skill-package-spec 位于 /home/cheng/works/chengrouter/community/。它们是独立的 Rust 项目，不是 chengflow Cargo workspace 的成员，也不得依赖 cheng-* crate。

前置条件

• Rust——工作空间使用 edition 2024，需要较新的 stable 工具链。
• Node.js ≥ 18 和 pnpm ≥ 9，用于前端。
• PostgreSQL——业务真相的唯一来源。
• Redis——核心可选，智能体记忆节点和调度器必需。
• Qdrant——可选，RAG 需要。

后端搭建

cd chengflow
cp .env.example .env
cargo run -p cheng-api        # 监听 :3000

.env 中的关键设置：

请为 TEST_DATABASE_URL 指定独立的测试数据库。测试对它指向的库是破坏性的。

不带参数的 cargo build 或 cargo run 只作用于 default-members——cheng-api 和 chengctl——而不是整个工作空间。要全部构建请用 cargo build --workspace。

前端搭建

cd chengflow-ui
pnpm install
pnpm dev                      # :5173，把 /api 和 /ws 代理到 :3000

Vite 开发服务器把 /api、/ws 及相关路径代理到 http://localhost:3000 上的后端（见 vite.config.ts）。:4000 上的老 Express 服务已废弃。

前端的环境变量必须以 VITE_ 为前缀。

pnpm build 需要后端在运行。 它会执行 gen:pages，该步骤调用后端渲染静态页面；后端不在时这一步会失败或跳过。可单独运行 pnpm gen:pages 重新生成页面。

数据库

cd crates/cheng-storage
diesel migration run          # 应用
diesel migration revert       # 回退最后一次
diesel print-schema > src/schema.rs

或者设置 RUN_MIGRATIONS=true，让服务器在启动时应用迁移。

常用命令

Rust（chengflow/、chengapp/）：

cargo build                   # 仅 default-members
cargo build -p cheng-core     # 单个 crate
cargo test                    # 整个工作空间
cargo test -p cheng-engine    # 单个 crate
cargo test test_workflow_creation
cargo test -- --nocapture
cargo check                   # 不生成代码——最快的循环
cargo fmt
cargo clippy

前端（chengflow-ui/、chengflow-sdk/、chengapp/）：

pnpm dev / build / preview
pnpm test                     # Vitest，watch 模式
pnpm test -- src/path/file.test.ts
pnpm test -- -t "test name"
pnpm test:integration         # Vitest 集成配置
pnpm test:e2e                 # Playwright
pnpm test:coverage
pnpm lint / lint:fix / format / type-check

chengapp 是混合工作空间，其 Rust 侧排除了 Tauri 客户端（src-tauri），因为它链接 webkit2gtk，而并非每台开发机都有。请单独构建：

cargo build --manifest-path src-tauri/Cargo.toml

i18n 工具

节点界面字符串由 chengctl 离线翻译——不需要数据库或服务器：

cargo run -p chengctl -- missing-i18n [--fail-if-missing]
cargo run -p chengctl -- dump-i18n-keys [--package builtin] [--output keys.json]
cargo run -p chengctl -- translate-missing [--engine baidu|llm] [--dry-run]
cargo run -p chengctl -- merge-i18n --base PATH --patch PATH

en-US 基线键从已注册的内置节点中抽取；zh-CN 放在覆盖文件里，未翻译条目标记为 [TODO-zh]。语言包位于 config/i18n。

API 文档与打包

make openapi      # 从代码生成 openapi.yaml
make docs         # OpenAPI、Swagger、Redoc、Postman、SDK、Markdown
make dev          # API 服务器加文档服务器
make test-api     # API 契约测试
./build.sh        # 发行二进制 + Docker / hybrid 包（--help 查看选项）

工作约定

• 除非被明确要求，不要创建文档或 *.md 文件。 这是后端自身指引里的硬性规定，在整个工作空间同样适用。
• 能把改动限制在一个子项目里就限制在一个子项目里。
• 读子项目自己的 CLAUDE.md 或 README.md——根文件只覆盖跨项目的内容。

下一步

• 架构详解——各层如何咬合。
• Crate 结构——什么住在哪里。
• 自定义节点开发——最常见的第一次贡献。