企业官网建设流程全解析

Routa 是一个以工作区（Workspace）为核心的多智能体协同平台，面向真实的软件交付流程。它把目标、任务、会话、追踪、评审状态放进同一个工作区里统一管理，并支持 MCP / ACP / A2A 协议，在 Web 与桌面端提供一致体验。这篇文章解释 Routa 为什么把 Workspace 当作第一等公民——这不是一句口号，而是一条写进架构决策记录（ADR）里的硬性边界。

从"全局大杂烩"到"工作区边界"：早期版本踩过的坑

很多 Agent 工具默认使用隐式全局作用域：会话、任务、看板都堆在一个"默认"上下文里。早期版本的 Routa 也这样，随着产品长大，暴露出三个典型问题（引自 docs/adr/0003-workspace-first-scope.md）：

• 不同项目的会话混在同一个列表里，找都找不到；
• 说不清哪个 Agent 配置、哪个 specialist 该作用于哪个仓库；
• MCP 工具的作用域含糊不清——执行git status时，到底指哪个仓库？

这三个问题在多仓库、多 Agent 场景下会被成倍放大。Routa 的答案是：把 Workspace 提升为顶层协同边界。

Workspace-first 的三个核心设计

1️⃣ 所有领域对象都归属于工作区

会话、任务、笔记、看板、代码库、worktree、记忆、定时任务——全部工作区作用域化。API 路由必须显式携带 workspace 上下文，否则视为"不完整的端点"。相关实现：

• 工作区模型定义：src/core/models/workspace.ts
• 工作区感知的服务装配：src/core/routa-system.ts
• Rust 侧工作区状态：crates/routa-core/src/state.rs
• 工作区作用域 API：src/app/api/workspaces/[workspaceId]/route.ts

顶栏先选 Workspace，再看板、仓库、Agent 都挂在这个边界之下

2️⃣ Codebase 成为一等记录，而不是工作区的附属字段

在 docs/design-docs/workspace-centric-redesign.md 中，Routa 把"仓库路径 + 分支"建模为独立的 codebase 记录，而不是直接写死在工作区上。这解锁了关键能力：一个工作区可以挂多个代码库。前后端两个仓库、主库加插件库，都能在同一块看板里被不同 Agent 分工处理，彼此边界清晰。

3️⃣ 导航、协议与桌面端共享同一套语义

• UI 导航先选工作区，再下钻到其中的会话、看板和代码库，切换入口在 src/client/components/workspace-switcher.tsx；
• Web（Next.js）与桌面（Tauri + Axum）实现可以不同，但 workspace / codebase 的 API 语义必须对齐，共同遵守 api-contract.yaml；
• MCP 工具在执行前先解析工作区上下文，从根上解决"工具在哪个仓库里执行"的问题。

左侧 433 个会话按工作区过滤，右侧 Agent Trace 中明确注入了当前 workspace 上下文

多 Agent 如何在一个工作区里协作？

Workspace-first 不是为了让 Agent 各干各的，而是给多 Agent 协作提供共享坐标系。Routa 的看板同时是规划界面和协同总线：每张卡片流转经过 Backlog → Todo → Dev → Review → Done 泳道，每个泳道背后是独立的 specialist prompt 合同（完整泳道合同表见 README.zh-CN.md）。

以"Backlog Refiner 只澄清范围不许编码、Review Guard 必须逐条独立验证验收标准"为例——这些严格边界之所以能成立，前提就是所有 Agent 都在同一个工作区边界内读写同一批结构化卡片，而不是在各自的私聊线程里各自为战。

会话详情左侧的 Kanban Story 面板显示卡片当前泳道与所属任务，Agent 的每次工具调用都可追溯

这套哲学对普通用户意味着什么？

如何验证与上手？

• 权威架构边界与不变量：docs/ARCHITECTURE.md
• Workspace 重设计现状与迁移说明：docs/design-docs/workspace-centric-redesign.md
• 平台核心概念（核心循环、主要对象）：docs/core-concepts/how-routa-works.md
• 数据库 schema 中的 workspace 相关表：src/core/db/schema.ts

从源码运行（Web）：

git clone https://gitcode.com/gh_mirrors/ro/routa cd routa npm install --legacy-peer-deps npm run dev

打开http://localhost:3000，创建一个 workspace、接入一个仓库，就能体验"先选工作区、再展开资源"的导航逻辑。

写在最后

单 Agent 聊天适合处理孤立任务，但一旦同一条线程同时承担拆解、实现、评审和证据收集，语义边界就会迅速崩溃。Routa 坚持 Workspace-first，本质是把"边界"从隐式约定变成显式架构约束：API 必须带 workspace scope、MCP 工具先解析上下文再执行、新端点缺 scope 即视为未完成。在多仓库、多 Agent 成为常态的时代，这条看起来"不性感"的纪律，恰恰是让 AI 协作保持可恢复、可审计的地基。