跳到主要内容

4. U1 总结

前面几篇已经把 Rust 项目、Ink 前端项目和 Rust xtask 自动化入口分别展开讲了一遍。到这里，KQode 的第一个 commit-sized 单元 U1 可以先做一次小结。

U1 对应计划文档里的 U1. Verify the Bun-powered nested Ink package scaffold，最终落地在 commit 99949b9fe7698a1f0b87acda232281cbaeb4d81d。这个单元的目标是先搭一套方便后续研发的脚手架：包括前端 Ink TUI 脚手架、Rust 后端项目基础，以及统一开发流程的 xtask 自动化脚手架。

到目前为止完成了什么​

U1 先把仓库调整成 Rust package + workspace 形态。根目录 Cargo.toml 保留原来的 KQode runtime package，同时把 xtask/ 加入 workspace：

[workspace]
members = [".", "xtask"]
resolver = "3"

这样 Rust 主项目和项目自动化命令可以共用 Cargo 工作区，但又不会提前拆成未来规划里的多 crate 架构。U1 只做当前阶段需要的最小结构调整。

前端侧新增了嵌套的 tui/ package。它使用 Bun 管理依赖，使用 Ink + React 渲染终端界面，并通过 tui/main.tsx 启动。当前的 tui/src/App.tsx 只展示 KQode 版本、当前 workspace cwd 和 backend-only 预览提示，足够验证 Ink 渲染链路。

为了避免开发者直接记忆 cd tui && bun ... 这类命令，U1 同时新增了 Cargo-facing 的 TUI 自动化命令：

cargo xtask tui-install
cargo xtask tui-typecheck
cargo xtask tui-test
cargo xtask tui-dev

这些命令注册在 xtask/src/commands/tui/mod.rs，实际执行逻辑复用 xtask/src/support/bun.rs 和 xtask/src/support/paths.rs。仓库还通过 .cargo/config.toml 配置了 cargo xtask alias，让 contributors 不需要写完整的 cargo run -p xtask -- ...。

U1 也补了 fixture workspace。提交里新增了一个最小的 tests/fixtures/dummy-react-app/，它不是 KQode 自己的前端，而是给 tui-dev 提供一个真实一点的工作目录。tui-dev 会把 fixture 准备到 target/kqode-test-workspaces/workspace/，然后从这个 workspace cwd 启动 TUI，让界面显示的是被操作项目路径，而不是 tui/ package 路径。

测试方面，U1 覆盖了几个基础面：

技术决策​

  • TUI 使用嵌套 Bun package，而不是把整个仓库变成根目录 JavaScript workspace。KQode 的核心方向仍然是 Rust-first，TypeScript 只是 UI surface。把前端放在 tui/ 下面，可以让 Ink 项目使用适合自己的工具链，同时不让根目录被 package-manager 配置接管。

  • 对 contributors 暴露 Cargo-facing 命令。即使底层是 Bun、tsx、Vitest 或 Vite fixture，日常入口仍然是：

    cargo xtask ...

    这样文档、IDE run profile、CI 和本地命令行可以复用同一组自动化命令。以后如果底层工具调整，只需要改 xtask 实现，不需要让所有调用方一起改命令。

  • tui-dev 从 workspace cwd 启动，而不是从 tui/ 目录启动。Coding Agent 真正服务的是用户当前项目，不是它自己的 UI package。即使现在界面只显示几行文字，也要先把 cwd 语义放对，否则后面接入文件引用、Git 状态、工具执行和审批时都会返工。

  • Fixture 是只读种子，真实运行使用 target/ 下的 ignored workspace。提交里的 dummy React app 用来提供可复制的初始状态，但测试和手工运行不直接污染 fixture 源目录。这保证 fixture 可以长期保持稳定，也让每次运行都能从全新的 workspace 开始。