【免费下载链接】routaWorkspace-first multi-agent coordination platform for AI development, with shared Specs, Kanban orchestration, and MCP/ACP/ A2A support across web and desktop.项目地址https://gitcode.com/gh_mirrors/ro/routa点击查看免费下载Routa 是一个工作区优先的多智能体协作平台Workspace-first multi-agent coordination platform它同时提供 WebNext.js与桌面Tauri Rust/Axum两种形态。这两个后端由完全不同的语言编写却对外暴露完全一致的 API 语义——这套「双后端架构」正是 Routa 区别于其他 AI 开发工具的关键设计。本文将从契约文件、组装点、一致性检查与行为级测试四个层面完整拆解它是怎么做到的。为什么是「双后端」而不是「两个产品」一个很自然的做法是Web 版和桌面版各自独立开发、共享一套前端界面。这条路短期很快但长期有隐患——两套后端会逐渐形成不同的领域概念、不同的字段命名、不同的错误码最终演变成两个心智模型割裂的产品。对「人与 Agent 共用一个工作区」的平台来说这种漂移是不可接受的。Routa 在项目早期就把这个问题固化成了架构决策记录ADR明确了一个核心结论Web 和桌面是同一个产品只有两个运行时表面runtime surface。完整决策文档见 0001-dual-backend-semantic-parity.md。它要求两个后端做到三件事共享同一套领域词汇workspace工作区、session会话、task任务、kanban board看板、specialist专家、worktree工作树……任何一侧先出现的新概念都不算「发布」必须双端落地。暴露同一形状的 API由仓库根目录的 api-contract.yaml 统一管理。在 CI 中运行契约一致性测试npm run api:test:nextjs对比npm run api:test:rust同一套测试脚本分别打向两个后端。一个容易忽略的细节是存储可以不同语义不能不同。Web 版跑在 PostgresNeon Serverless上桌面版跑在本机 SQLite 上但两端的 store 接口与领域语义必须保持一致。契约先行api-contract.yaml 是唯一事实来源Routa 采用「契约优先」Contract-First的 API 治理方式。所有端点、请求/响应结构、枚举值先定义在一份 OpenAPI 3.1 规范里再分别去两个后端实现。这份契约文件有 7000 多行开头就写明了规则openapi: 3.1.0 info: title: Routa.js API Contract description: | Single source of truth for the Routa.js dual-backend API. Both the Next.js backend (src/app/api/) and the Rust backend (crates/routa-server/) MUST implement all endpoints defined here with compatible request/response shapes.几个值得注意的设计点枚举集中定义。像TaskStatusPENDING / IN_PROGRESS / REVIEW_REQUIRED / COMPLETED…、AgentStatus、VerificationVerdict这类状态机枚举在契约的components.schemas中统一定义一次两个后端必须使用完全相同的取值。这样任务状态在 Web 和桌面之间切换时不会出现语义错位。服务器声明即双端口。契约里直接声明了两个服务地址Next.js 后端localhost:3000与 Rust 后端localhost:3210契约文件本身就描述了「一个产品、两个运行时」的结构。变更有流程约束。按 api-contract.md 中的规则添加新端点必须先改契约、再双端实现、最后跑npm run api:check验证破坏性变更默认禁止必须走版本化或废弃流程。对称的组装点TypeScript 与 Rust 各有一个「系统工厂」契约管的是「API 长什么样」而「系统怎么组装」则由两个对称的工厂函数保证。ADR 中明确指出了这两处角色TypeScript 侧Rust 侧组装点src/core/routa-system.tscrates/routa-core/src/state.rsTypeScript 侧的RoutaSystem是一个中心对象持有全部 storeagent、task、workspace、kanban board、note……、事件总线EventBus与工具集AgentTools、NoteTools、WorkspaceTools并支持 InMemory / Postgres / SQLite 三种存储模式。Rust 侧的AppStateInner结构体做了完全对称的事情同样是 workspace_store、agent_store、task_store、kanban_store、note_store、event_bus 等成员一一对应外加 ACP 管理AcpManager、AcpRuntimeManager等桌面端运行所需的能力。这种「镜像式组装」保证了无论从哪个后端进入系统拿到的都是同一组领域服务、同一套事件语义。前端与 Agent 只需要按契约调用不用关心背后是谁在响应。三层防线静态检查 行为测试 健康度门禁光有契约文件不够Routa 用三层自动化防线确保契约不被悄悄破坏。第一层路由静态对账api:checkcheck-api-parity.ts 会同时从三个来源提取路由定义并做差集对比解析api-contract.yaml中声明的端点扫描 Next.js 的文件约定路由src/app/api/ 下的route.ts导出函数解析 Rust 侧 Axum 路由crates/routa-server/src/api/ 各模块的router()定义。输出报告包含missingInNextjs/missingInRust/extraInContract等字段——哪一侧漏实现了契约端点、哪一侧私加了契约外端点都会被列出来。该检查支持--json机器可读输出和--fix-hint修复建议。第二层行为级契约测试同一套脚本打两个后端tests/api-contract/ 目录下的测试运行器 run.ts 是关键它把同一套用例workspaces、agents、tasks、notes、sessions、skills、schema-validation 七个套件分别指向BASE_URLhttp://localhost:3000Next.js和BASE_URLhttp://localhost:3210Rust验证的是行为一致性而不只是路由存在性。对应脚本命令定义在 package.json 的api:test:nextjs/api:test:rust中。针对 Rust 后端还有专门的端到端测试矩阵 rust-api-test.md按「端点 × 场景」登记每个用例的状态VERIFIED已验证并给出测试文件路径、BLOCKED有阻塞原因、TODO待补齐。覆盖范围包括成功路径、负向路径如空名创建返回 400、缺失参数返回 404、非法状态转移返回冲突和回归路径例如POST /api/tasks/{id}/status必须验证无效状态转移会被拒绝——这类状态机语义正是「语义对齐」最容易悄悄漂移的地方。第三层健康度体系中的硬门禁契约检查不是独立脚本而是接入了 Routa 的 fitness工程健康度评分体系。在 api-contract.md 中api_contract维度的openapi_schema_valid和api_parity_check两个指标都标记为hard_gate: true——也就是说 Schema 校验失败或双端不一致时门禁直接不放行。Rust 侧端点测试同样登记在 rust-api-test.md 的前置元数据中作为 maintainability 维度的证据来源。整套健康度文件清单见 manifest.yaml。对使用者的实际意义这套架构对普通用户意味着什么三个具体好处数据与体验跨端一致在 Web 上创建的工作区、看板卡片、任务状态切到桌面端打开时概念完全对得上不需要「翻译」。桌面端是本地优先的按 desktop.md 的说明桌面版提供 local-first 持久化与执行能力而 Web 版适合自托管和团队浏览器访问web.md两者只是部署形态差异。新能力双端同步落地任何新领域概念必须双端实现后才算发布不会出现「Web 有、桌面没有」的半拉子功能。关键文件速查文件作用api-contract.yaml双后端 API 契约唯一事实来源docs/adr/0001-dual-backend-semantic-parity.md双后端语义对齐的架构决策记录src/core/routa-system.tsTypeScript 侧系统工厂crates/routa-core/src/state.rsRust 侧共享应用状态scripts/fitness/check-api-parity.ts三源路由静态对账脚本tests/api-contract/双后端行为级契约测试docs/fitness/api-contract.md契约维度健康度门禁配置docs/fitness/rust-api-test.mdRust 端点测试矩阵总结Routa 的双后端架构可以概括为一句话契约先行定义语义镜像组装保证结构自动化门禁守住底线。一份 OpenAPI 契约作为唯一事实来源两个语言的系统工厂对称组装相同的领域服务再叠加静态路由对账、行为级对比测试和 hard gate 健康度门禁让 Next.js 与 Rust/Axum 这对「异卵双胞胎」始终说同一种 API 语言。对任何需要同时维护 Web 与桌面两个运行时的项目来说这套「契约 镜像 门禁」的组合都值得直接借鉴。赞分享【免费下载链接】routaWorkspace-first multi-agent coordination platform for AI development, with shared Specs, Kanban orchestration, and MCP/ACP/ A2A support across web and desktop.项目地址https://gitcode.com/gh_mirrors/ro/routa点击查看免费下载相关推荐Rust Crates.io 后端架构深度解析Rust Crates.io 后端架构深度解析 概述 Crates.io 是 Rust 编程语言的官方包注册中心承载着整个 Rust 生态系统的核心基础设施。后端前端开发工具CCPD车牌定位网络wR2核心技术揭秘CCPD车牌定位网络wR2核心技术揭秘 CCPDChinese City Parking Dataset是一个多样化且标注完善的车牌检测与识别数据集而wR数据集计算机视觉Tabularis架构深度解析React 19前端与Rust Tauri v2后端如何构建跨平台SQL工作台Tabularis架构深度解析React 19前端与Rust Tauri v2后端如何构建跨平台SQL工作台 Tabularis 是一款开源桌面 SQL 工作创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考