Agent Workspace：把一次性 AI 对话变成可积累的研发系统

文档范围

Workspace 在 Agent 产品里没有统一含义。Google Workspace Studio、Gemini Code Assist、腾讯云智能体开发平台、通义灵码 / Qoder 和美团 CatPaw 都会使用这个词，但各自约束的对象不同：有的管文件视野，有的管一次任务的运行现场，有的管租户权限，有的管用户侧工作台。

本文讨论尚未被上述产品单独定义、却最容易和它们混用的一层：团队级 Agent Workspace。它回答的问题是：Agent 在这个项目里应当依据哪些已确认事实工作、能执行哪些动作、怎样证明完成、哪些经验可以留给下一次任务。它位于单个代码仓库之上、单次任务之外，由治理条件对齐的项目长期维护。一个团队可以维护多个 Workspace。

后文单独出现的 Workspace，默认都指这一层。其他产品中的 Workspace 只用来对照边界，不作为本文的实现标准。

这套方案把优化单位从一次 Prompt 或一次 Session，提升为可被团队反复消费的 Agent Harness：围绕模型组织上下文、工具、权限、流程和验证。建设是否有效，不看目录是否填满，而看真实需求能否走完 Spec、Coding、Review、Verify，以及评审后的经验能否被后续任务复用。

官方产品里的四种 Workspace

公开文档里至少能分出四层。先确定它约束的对象，再讨论目录、Worktree、Session 或权限。

图 1：同一套 Agent 系统可以同时具有四层。权限外壳、团队能力、任务现场和文件视野不能共用同一个生命周期。

腾讯云把平台写成「企业 → 工作空间 → 智能体应用」：企业负责谁可以进来，工作空间负责团队共享哪些资源，应用负责具体能办什么事。Google Cloud 的 Agent Platform 则按 Build / Scale / Govern / Optimize 组织生命周期。这两套官方分层都有用，但它们回答的是租户、运行时和治理基础设施，并不自动产生某个业务项目的仓库地图、验收标准和故障结论。

阿里的 Quest 把 Local 与 Worktree 分成两种执行环境：Local 直接改主工作区，Worktree 在隔离副本里执行，确认后再合并。美团 CatPaw 把「AI 智能工作台」和「Managed Agents」分开：前者是用户侧执行与多端协同，后者是企业级托管、隔离和运维。这些都是执行层或平台层的设计。团队级 Workspace 要补的是它们默认不会替业务团队维护的那包项目真相。

研发现场中的系统缺口

是否需要这一层，取决于 Agent 在真实研发任务里反复卡在哪里。

这些问题不能只靠换更强的模型解决。真实研发发生在多仓库、多环境、多系统和多人经验之上。模型看不到的事实、不能执行的动作、没有定义的验收标准，都属于 Harness 缺口。

因此目标不是「Agent 知道更多」，而是让它逐步具备四件事：

知道去哪里查 → 知道如何执行 → 知道怎样证明完成 → 知道哪些经验值得留下

Google 的 Agent Mode 已经把「读工作区 + 调工具 + 等人批准」做成了客户端能力；阿里的 Agent 模式也覆盖工程检索、多文件编辑和终端执行。缺的通常不是这一次怎么改文件，而是下一次新 Session 是否还要口头补同一套项目规则。

团队级 Workspace 的定义

团队级 Workspace 是：面向项目，组织 Agent 研发所需上下文、工具、流程、验证环境和经验回写机制的长期操作空间。

它长期存在，可以被多个需求、成员、代码仓库和 Agent 客户端共同消费。一次任务结束后，执行现场可以归档；经过评审的项目能力继续服务下一次任务。

它不是新建一个仓库，也不是把多个业务仓 clone 到同一目录。仓库只提供代码可见性。缺少业务语义、修改边界、验证入口和回写门槛时，Agent 仍然没有可积累的工作方式。

GEMINI.md、AGENTS.md 或项目级自定义 Agent 仍然值得写。Google 把它们当作分层上下文，阿里把自定义 Agent 放到用户级或项目级目录。它们是入口规则，不是 Workspace 的全部。

五层资产与三个平面

分层用来发现能力缺口，不是要求先把所有目录填满。

知识层的关键是查询路由，而不是把所有资料复制进同一个仓库。长期有效的规则、架构和契约适合版本化保存。需求状态、日志、监控和环境运行状态应通过 Connector 在使用时实时查询，并在索引中标明权威来源。

为了让任务可复现，每个隔离任务现场固定消费稳定资产、Workflow 和工具的版本。实时查询不冻结成长期事实，但应记录来源、查询参数和时间；必要时把结果快照作为本次任务证据。

环境说明与凭据必须分离。Workspace 可以保存如何申请、如何注入、如何验证权限，不应把 Secret 直接写进仓库。CatPaw Managed Agents 把凭证托管和运行环境隔离写成平台能力，方向相同：Agent 使用权限，但不直接持有敏感材料。

这五层可以整理成三个平面：

• 上下文平面：代码、知识和环境，回答项目是什么、事实在哪里。
• 能力平面：工具层，回答 Agent 能稳定执行什么。
• 治理平面：流程、验证、评审和度量，回答何时可以继续、什么可以长期沉淀。

图 2：缺少任何一个平面，Workspace 都会退化成资料库、脚本箱，或没有验收标准的自动化。Execution Workspace 在创建时消费这些能力；任务结束后，只把经 Review 的增量送回。

最小边界与四项治理测试

切 Workspace，切的是 Agent 每次开工都会默认加载的那包已批准事实。范围太大，做 A 项目时会读到 B 的规则；范围太小，一个真实需求要跨多个 Workspace 才能改完。

默认按一个项目来切。这里的「项目」不是单个 Git 仓库，也不是整个部门，而是四项治理条件都能对齐的工作范围：

1. 共同 Repo 路由
2. 共同事实 Owner
3. 共同权限边界
4. 共同发布节奏

一个产品下的多个业务仓库，只要这四项对齐，仍应放在同一个 Workspace。一个团队如果同时做治理条件明显不同的几摊工作，就应维护多个 Workspace。

• 应合并：一个客户端产品同时有应用仓、模块仓和 overlay 仓，但共用一张仓库地图、同一批领域 Owner、同一圈工程权限，规则也跟着同一产品版本发布。多仓仍是一个 Workspace。
• 应拆开：同一组人既做客户端交付，也做离线数据分析。仓库入口、事实责任人、数据权限和规则更新频率都不同。做客户端时不应默认加载分析口径，跑分析时也不应默认加载客户端验收 Skill。

图 3：四项测试对齐时，共享的是已评审、已版本化的项目真相。任一项明显不对齐，就拆开；骨架用模板复用，不含项目事实的通用动作用 Plugin 复用。

腾讯云允许按事业部、项目或环境划分工作空间，并强调空间之间数据、配置和成员权限隔离。Google Cloud 用 Agent Identity、Registry、Policy 和 Gateway 控制谁能调用哪些目的地。这些官方能力处理的是租户和运行时权限。团队级边界还要额外判断：这包项目事实能不能被同一批 Owner、按同一发版拍子批准。

多个项目只有在四项都对齐时，才共享同一包稳定资产。共享的不是 Issue、执行现场和凭据。权限圈、Owner 或发布节奏明显不同时，应拆成不同 Workspace。

拆开后，公共能力不要靠再做一个超级 Workspace 来复用：

项目真相跟 Workspace 走。不要为了共用登录、沙盒或审计，把两套项目事实放进同一份默认上下文。

研发交付闭环

目录和资产只是输入。交付闭环判断的是：一次真实需求能否按已定义的阶段、产物和退出条件做完。

一条完整交付链路可以写成：

理解目标
→ 查询稳定知识
→ 查询实时状态
→ 澄清并形成 Spec
→ 在隔离现场编码和测试
→ Review 与修复
→ 真实环境验证
→ 交付与总结

每个阶段都应定义四件事：输入是什么、要调用哪些能力、产物是什么、什么条件下才能退出。Verify 不能只写「运行测试」，还应指定环境、操作步骤、期望终态和证据格式。任何关键步骤失败，都应回到 Coding 或问题诊断，而不是用其他绿色信号抵消。

阿里 Quest 的 Spec 驱动场景先对齐需求、方案和验收标准再执行，和这里的 Spec 阶段同向。差别是：Quest 产物默认服务这一次任务；团队级 Workspace 要求同一份规格还能被后续 Coding 与 Verify 消费。

上述交付链路运行在 Execution Workspace 中，但它消费的项目知识、规则和验证能力来自长期 Workspace。

经验回写与稳定资产

交付结束后，Session、日志和 Diff 只是活动记录，不能自动变成下一次任务的稳定知识。更安全的回写链路是：

活动记录 → 候选增量 → 证据验证 → 领域 Owner Review
→ 发布新的 Workspace 版本 → 在后续任务中复用与度量

图 4：Delivery Review Gate 只判断本次代码和交付证据能否通过。随后提炼出的候选资产还要经过证据复核和领域 Owner Review，才能发布到新的 Workspace 版本。

值得回写的内容通常包括已确认的业务规则、接口契约、稳定复现的故障结论、重复出现的操作步骤，以及可复用的 Skill、Script、Test、Hook 或模板。CatPaw 允许把高频流程录制成技能，并按团队或角色下发；那是能力沉淀。进入稳定上下文之前，仍然需要来源、Owner 和评审状态。

每项候选资产至少需要：

还应区分三类对象：

• 事实源：代码、正式接口契约、已批准 Spec 和平台实时状态。
• 派生资产：概览、索引、操作指南和 Skill references，应能追溯或重新校验。
• 活动记录：Session、执行记录、日志和失败现场，用于审计和发现候选知识，默认不直接加载为稳定规则。

不同事实类型需要预先指定权威来源：代码行为以受版本控制的代码和测试为准，需求语义以批准的 Spec 为准，接口以正式契约为准，环境状态以实时查询为准。来源冲突或资产超过 revalidate_by 时，Agent 应停止把它当成稳定事实，降级为待确认线索并请求相应 Owner 处理。默认上下文只加载仍处于 approved + verified 状态的资产。

「自我进化」的合理边界是自动发现和起草，人负责确认事实、批准版本与撤回错误资产。没有这道门槛，Workspace 会把一次任务中的猜测放大到所有后续任务。跨会话记忆可以记住个人偏好，但不能绕过项目事实的 Owner Review。

建设路径：层级、流程与角色

分层、分流程和分角色不是三选一：

• 分层建设回答当前建到什么能力水平。
• 分流程建设回答研发链路的哪个环节还缺能力。
• 分角色建设回答谁负责维护和评审这类事实。

三条轴叠加后，任何一项资产都能被定位。例如「页面验收 Skill」可以处于 L2 或 L3，服务 Verify 流程，由产品、设计和测试角色共同确认验收语义。

分层建设

L1–L3 是渐进建设模型，不是行业标准。每一级都应是能独立获益的稳定状态，可以长期停留。升级条件是更长的真实任务闭环已经稳定跑通，而不是目录数量增加。从 L1 到 L3 按能力地板递进：先能安全进入，再能完成微循环，最后能验证并回写。

图 5：L1 解决安全进入，L2 解决按流程执行，L3 解决真实验证和受控回写。团队可以长期停留在能产生实际收益的层级。

L1：Agent 能安全进入项目

最小资产包括项目说明、Repo 路由、读写边界、启动方式和一个基础验证入口。验收方式不是检查文档数量，而是让一个没有额外口头背景的新 Session 找到正确仓库、启动项目并跑通基础检查。

L2：Agent 能完成真实研发微循环

在 L1 上补充高频 Skill、确定性 Script、测试入口和 Review 卡点。验收是一项真实需求能完成「编码—测试—修复—评审」微循环，并保留可复查产物。

L3：交付有证据，经验可回写

补充真实环境验证、结构化报告、候选资产、Owner Review、版本发布和腐化巡检。验收不只是本次完成，还要观察评审资产是否在后续同类任务中再次命中。

分流程建设

不需要先为所有研发阶段设计完整系统。可以选择最频繁、代价最高或最容易验证的一条流程开始。

按流程建设的关键不是给每个阶段写文档，而是把入口规则放到 Agent 可发现的位置，把确定性动作放进 Script，把可复用做法放进 Skill，把阶段门槛放进 Workflow 或 Hook。

分角色建设

Workspace 的目标不是让产品、研发、测试和运维依次把任务交给下一个角色，而是让「任意一名成员 + Agent」能够借用其他角色已经确认的上下文完成更多工作。

角色知识不应各自形成隔离目录。更合适的组织方式是：产品规则进入 Spec 和知识索引，仓库事实跟随 Repo，测试与运维做法进入对应 Skill 和 Workflow。角色约束的是谁能把内容写成稳定事实；同一权限圈内的成员和 Agent 都可以消费已确认上下文。权限边界决定谁进得了这个 Workspace，不决定内部再按角色把知识锁进孤岛。

起步时，每个角色只选出 3～5 个「其他人最常来问、自己又反复回答」的问题，先让 Agent 基于现有 Workspace 作答。回答不完整的部分再补资产，并把这些资产挂到实际流程中。这种问答验收比一次性编写完整角色手册更容易发现真实缺口。

平台能力与业务事实

规模化的前提是平台与业务团队边界清楚。官方产品已经把这件事写进架构：腾讯云把企业准入和工作空间资源分开；Google Cloud 把 Build 和 Govern 分成不同支柱；美团把工作台使用和企业托管分开。团队级 Workspace 沿用同一原则：平台提供骨架和底线，业务团队维护领域事实。

平台提供三层可复用骨架

Secret、审计、模板升级和通用安全护栏也属于平台能力。平台负责协议和基础设施，具体项目内容仍由业务团队维护。

业务团队维护领域事实

业务团队必须负责：

• 业务概念、产品规则和真实验收标准；
• Repo 职责、模块边界和可运行测试入口；
• 环境差异、故障经验和回滚约束；
• 候选知识、Skill、Workflow 与验证结论的 Review。

平台可以生成初稿、提供模板和自动巡检，但不能替领域负责人确认事实。业务团队也不应在每个项目中重复实现认证、沙盒、审计和活动记录。

适合长期运行的治理方式是：骨架与底线自上而下建立，内容和实践自下而上生长，所有稳定变更通过对应 Owner 评审。 这样既保留团队试验空间，也避免每个 Workspace 演变成无法复用的私有目录。

最小可验证实现

第一版不需要先建设完整平台或模板市场。选择一个真实项目和一条高频流程，按三个阶段验证即可。

逻辑骨架

下面是逻辑骨架，不是强制目录标准：

workspace/
├── AGENTS.md
├── repos/
│   ├── index.md
│   └── <repo>/
│       ├── overview.md
│       ├── setup.md
│       └── test.md
├── docs/
│   ├── glossary.md
│   ├── architecture.md
│   └── product-specs/
├── skills/
├── workflows/
├── evidence/
└── candidates/

• AGENTS.md 只保存入口规则、路由和安全边界，不承载全部知识。
• repos/ 保存仓库地图和各仓说明，不是把业务代码复制进 Workspace。Agent 先在这里判断涉及哪些仓库，再读取各仓启动与测试方式。
• docs/ 保存稳定领域知识；实时需求、日志和环境状态通过 Connector 查询。
• skills/ 与 workflows/ 保存可执行做法和阶段卡点。
• evidence/ 保存证据索引或受控系统中的稳定链接，candidates/ 保存尚未批准的经验增量。大型日志、敏感数据和实时结果不直接入库，应保留在有权限与保留周期控制的系统中。

初始化可以由 Agent 扫描 Repo 结构、README、接口、测试入口和历史 Session，生成第一版索引与候选资产。自动化只负责降低起步成本；仓库边界、业务语义、凭据暴露和历史结论仍需相应 Owner 审核。

三个验收阶段

1. 验证 L1：不额外解释项目，让新 Session 找到正确 Repo、启动项目并完成基础检查。
2. 验证 L2：选择一项边界清楚的需求，跑通 Spec、Coding、测试和 Review。
3. 验证 L3：用一个任务在真实环境完成验收、提炼候选资产并经 Owner Review 发布；再用下一项同类任务验证它是否被正确复用。

用结果指标判断是否继续投入

文档数、Skill 数和调用次数只能说明发生了建设活动。更接近实际价值的指标包括：

• 每个任务需要人工补充背景的次数；
• 从 Issue 创建到首个可评审结果的时间；
• 首次验证通过率和人工接管率；
• Review 后返工次数与缺陷逃逸率；
• 历史知识或 Skill 命中后的任务成功率；
• 候选资产通过 Review 后在后续任务中再次采用的比例。

这些指标需要固定任务类型和统计分母，并与建设前基线对照。单次成功、资产数量增长或调用次数增加，都不能单独证明 Workspace 有效。

任务控制中的对象模型

如果把这套方案接入一个通过页面控制 Codex、Claude Code 或其他 CLI Agent 的工具，需要把长期能力定义与单次任务现场分开。这是结合任务看板做的延伸，不是参考方案中的固定产品模型，也不是 Google Agent Runtime 或阿里 Quest 的官方对象名。

Issue 与 Execution Workspace 应使用两套状态机：

Issue：Backlog → Ready → In Progress → Review → Done
 
Execution Workspace：
Provisioning → Running ↔ WaitingForUser
Running → Succeeded / Failed → Archived

一个 Issue 可以关联多个 Execution Workspace；一次执行失败不等于业务任务失败。Worktree 只是执行现场中的代码隔离组件，也不等于长期 Team Workspace。创建执行现场时应固定所消费的 Team Workspace 版本，避免任务运行过程中规则静默变化。

控制层真正需要提供的是 Agent Adapter、Session 恢复、结构化 Intervention、终端与证据展示，以及 Issue 和执行事件之间的映射。项目知识和团队规则仍由 Team Workspace 长期维护。

建设约束

• 把 Workspace 做成文档仓库：资料没有查询路由、可执行动作和验证证据时，不会改善交付。
• 一开始填满五层：没有真实任务驱动的资产难以判断价值，也会快速过期。
• 让 Agent 自动写入稳定知识：自动提炼可以默认开启，自动批准不应默认开启。
• 按角色建立知识孤岛：角色负责 Review，资产应跟随被消费的流程与对象组织。
• 把活动数量当作效果：只有跨任务结果和复用数据才能证明收益。
• 把凭据写进 Workspace：环境说明、权限申请和 Secret 注入必须分离。
• 绑定单一 Agent 客户端：长期资产使用通用文件与协议，客户端差异留在 Adapter。
• 混合业务状态和运行状态：Issue、Execution Workspace、Session 与 Run 各自拥有生命周期。
• 把平台租户当成项目 Workspace：腾讯云工作空间或 Dify Workspace 解决的是谁能访问哪些应用和知识库，不自动等于某一业务项目的 Repo 路由和验收标准。

判断建设是否有效，可以回到一个具体问题：新的 Agent Session 是否无需重复口头解释，就能找到正确事实、完成受控执行、拿出验收证据，并把经评审的经验交给下一次任务复用。

资料来源

• 一份未公开的团队 Agent Workspace 建设材料；文中只保留可泛化的方法，不引用组织、人员、平台或业务信息。
• 公开产品文档，访问于 2026-09-19：
  • Google Workspace：Introducing Workspace Studio
  • Google：Gemini Code Assist Agent Mode
  • Google：Use agent mode
  • Google Cloud：Gemini Enterprise Agent Platform Overview
  • Google Cloud：Agent Platform Govern
  • 腾讯云：智能体开发平台架构
  • 腾讯云：企业、工作空间与权限概述
  • 阿里云：通义灵码智能体
  • 阿里云：Quest 概览
  • 美团技术团队：CatPaw
  • Cline：Multi-Root Workspaces
  • Vibe Kanban README
  • OpenHands：Workspace Architecture
  • Dify：Workspace Overview
  • LangSmith：Administration Overview

相关笔记

• Agent Skills 完全指南
• Agent Hook 完全指南
• Agent Plugin 完全指南
• Codex Plugin CC 05 任务生命周期状态机
• 把需求写成可验证的 Spec
• 1. 查看当前 worktree（默认只有一个）