# bt-forge **Repository Path**: waidais/bt-forge ## Basic Information - **Project Name**: bt-forge - **Description**: No description available - **Primary Language**: Unknown - **License**: Not specified - **Default Branch**: master - **Homepage**: None - **GVP Project**: No ## Statistics - **Stars**: 0 - **Forks**: 0 - **Created**: 2026-05-25 - **Last Updated**: 2026-07-17 ## Categories & Tags **Categories**: Uncategorized **Tags**: None ## README # bt-forge `bt-forge` 是一套通用行为树编辑与编译工具链：用语言无关的 IR 表达入口与命名行为树，配套静态校验、编译、解释执行、代码生成、导入解析、调试与编辑器后端服务。 DSL / LSP 最终基线已于 2026-07-16 完成 / REVIEWED；“最终”只覆盖已冻结范围，正式裁剪项、测试盲区与平台/runtime 边界见 [最终风险清零报告](docs/reports/2026-07-16-dsl-lsp-final-risk-clearance.md)。 它不是某个宿主项目的运行时，也不是前端 UI 仓库。核心目标是让行为树语义在 Graph Document、Semantic IR、Compiled IR、Interpreter 和 Codegen 之间保持一致。 --- ## 核心边界 - Graph Document 可以携带编辑器 UI 信息；Semantic IR / Compiled IR 不携带 UI 状态。 - Validator 只读校验，不修改 IR。 - Compiler 负责把源层语义 lowering 到 Compiled IR。 - Interpreter 和 Codegen 只消费 Compiled IR / IrBundle，不直接读取 Graph Document。 - Text DSL 源码声明统一使用 `local`；`run` 可调用静态 tree、external tree 或动态 Behavior，递归由默认 128 层运行时调用深度预算保护，Behavior outputs 只在 Success 时原子提交。 - Text DSL primitive 只使用 `bool/i32/i64/f32/f64/string`；`Option/Array/Result/Behavior/Shared` 保持 PascalCase，不提供旧拼写兼容。 - `Shared` 是显式 opt-in 的 runtime-local 共享 cell；普通赋值仍是逻辑复制/COW，不会因为引入 Shared 变成全语言引用语义。 - Rust public codegen path 由 `bt-codegen-rhai` 的 bundled Rust backend 承载。 - 主 authoring frontend 是 text DSL（`.btf`），将通过 LSP 接入用户编辑器（VSCode / Neovim / 等）。GUI 编辑器子项目已搁置，靠 git 历史复活；详见 `docs/archive/legacy-docs/2026-06-04/`。 历史任务进度、开发流水与审查日志已归档到 `docs/archive/`；当前任务入口只保留在 `docs/tasks/`。 --- ## 快速开始 第一次使用请从 [`docs/guides/dsl-quickstart.md`](docs/guides/dsl-quickstart.md) 开始。该指南从空目录创建一个双文件 DSL workspace，并真实走通格式检查、校验、Rust 目标预检、二进制 bundle 和 generated Rust package。 - 完整 config、manifest、blackboard、多文件 import、AOT 与 LSP 示例：[`examples/release-workspace/README.md`](examples/release-workspace/README.md) - Zed 全局 dev extension、VSCode Language Client 与 Neovim stdio 接入：[`docs/guides/editor-setup.md`](docs/guides/editor-setup.md) - Text DSL v3 语言参考：[`docs/architecture/text_dsl_design.md`](docs/architecture/text_dsl_design.md) - workspace config / manifest 契约：[`docs/modules/bt-import/data_contract.md`](docs/modules/bt-import/data_contract.md) - 仓库最终 DSL/LSP 一命令门禁：[`docs/guides/dsl-final-release-gate.md`](docs/guides/dsl-final-release-gate.md) `bt-lsp` 的 compiled/generated preview 当前是供宿主直接调用的 transport-free Rust service API，不是 LSP wire capability；通用编辑器 client 不应发送未定义的 preview 请求。 仓库贡献者的基础门禁： ```bash cargo build --workspace cargo test --workspace cargo fmt --all -- --check cargo clippy --workspace --all-targets --all-features -- -D warnings cargo run -p bt-cli -- --help ``` 最终 release 候选应运行： ```powershell powershell -ExecutionPolicy Bypass -File scripts/dsl-final-release-gate.ps1 ``` --- ## Crate 一览 | Crate | 职责 | | :-- | :-- | | `bt-core` | 共享 ID、slug / namespace 解析、`BtStatus` 等基础原语 | | `bt-diagnostics` | 统一诊断结构、错误码、source span、诊断目标与收集器 | | `bt-types` | 类型和值系统，包括 primitive、object、enum、array、option、result、Behavior、Shared 与 TypeRegistry | | `bt-registry` | NodeDef、TreeDef、Blackboard key、端口、配置参数与 manifest 描述 | | `bt-ir` | Graph Document、Semantic IR、Tree IR、Compiled IR、source map companion artifact 与 serde schema | | `bt-validator` | 拓扑、类型、local definite assignment、tree 输出路径、compiled shape 与 registry 规则校验 | | `bt-import` | import resolver、依赖图、registry merge、body resolver、cache digest 与 affected modules | | `bt-compiler` | Graph / Semantic / Tree IR lowering、slot 分配、debug map 与基础优化 | | `bt-codegen` | 语言无关 codegen 协议、GeneratedPackage、IrBundle 与执行级 precheck | | `bt-codegen-rhai` | Rhai codegen host 与 bundled Rust backend | | `bt-interpreter` | Compiled IR 解释执行、frame/state 管理、Behavior session 与 trace 产生 | | `bt-runtime` | 目标项目最小运行时协议、节点 ABI、blackboard / Behavior / array helper 与单线程 Shared heap | | `bt-runtime-macros` | Rust 节点声明与 executor 注册的过程宏人体工学 | | `bt-trace` | Trace 数据结构与对比工具 | | `bt-text-dsl` | `.btf` Text DSL parser、source lowering 与 validator facade | | `bt-lsp` | Text DSL diagnostics、hover、completion、definition、signature/inlay 与 workspace projection | | `bt-cli` | `bt-forge` 命令行入口，编排 validate / compile / generate / check / format / watch / run / dump，并支持 `.btf` 文件或 workspace 目录的 validate / compile-ir / check / format | 完整依赖方向见 [`docs/architecture/dependency_graph.md`](docs/architecture/dependency_graph.md)。 --- ## Runtime forest 双场景基准 开发期 128-instance parity 必须显式选择场景： ```powershell cargo run -p bt-forest-bench -- verify --scenario stateful --instances 128 cargo run -p bt-forest-bench -- verify --scenario decision --instances 128 ``` 正式测量使用 release，并为两个场景分别写报告： ```powershell cargo run --release -p bt-forest-bench -- measure --scenario stateful --instances 100000 --warmups 1 --samples 3 cargo run --release -p bt-forest-bench -- measure --scenario decision --instances 100000 --warmups 1 --samples 3 ``` 当前机器的完整口径与原始结果见 [`2026-07-14 Runtime Forest 双场景十万实例基准报告`](docs/reports/2026-07-14-runtime-forest-dual-scenario-benchmark.md)。 --- ## 文档入口 - 开发规则：[`AGENTS.md`](AGENTS.md) - 架构总览：[`docs/architecture/architecture.md`](docs/architecture/architecture.md) - 依赖图：[`docs/architecture/dependency_graph.md`](docs/architecture/dependency_graph.md) - 当前任务入口：[`docs/tasks/current_task.md`](docs/tasks/current_task.md) - 模块文档：[`docs/modules/`](docs/modules/) - ADR：[`docs/adr/`](docs/adr/) - Text DSL v3 设计：[`docs/architecture/text_dsl_design.md`](docs/architecture/text_dsl_design.md) - DSL / LSP 最终风险与边界报告：[`docs/reports/2026-07-16-dsl-lsp-final-risk-clearance.md`](docs/reports/2026-07-16-dsl-lsp-final-risk-clearance.md) - 全文审查流程：[`docs/reviews/full-project-review/README.md`](docs/reviews/full-project-review/README.md) - 历史归档：[`docs/archive/`](docs/archive/) --- ## 依赖约定 第三方依赖集中声明在根 [`Cargo.toml`](Cargo.toml) 的 `[workspace.dependencies]`。 库 crate 不引入 `anyhow` / `miette`；依赖方向和依赖策略由 `bt-cli` 的 policy / dependency graph 测试锁定。 --- ## 许可 MIT OR Apache-2.0。