agent space云端工作空间通过.aw.yaml配置实现git分支、docker环境、终端布局与状态持久化的一体化封装；需满足go 1.21+、存在pyproject.toml等工程文件、正确配置name和environment字段，方可启用依赖解析与沙箱功能。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
Agent Space云端工作空间专为代码项目设计，它把Git分支管理、Docker环境隔离、多终端布局和状态持久化全部封装进一个可复现的配置文件里，避免你在本地反复折腾Python版本冲突、npm install卡死或终端窗口散落一桌。
确认项目是否适配Agent Space的核心前提
打开终端进入你的代码根目录，执行ls -a | grep "pyproject.toml\|package.json\|go.mod\|Cargo.toml"。只要输出中出现任意一个文件名，说明该项目已被主流语言生态认可，Agent Space能自动识别工程类型并加载对应插件链。
若目录下只有零散.py或.js文件且无任何工程配置文件，Agent Space将无法启用依赖解析、测试运行和环境沙箱功能——此时必须先补全requirements.txt或package.json，否则后续所有操作都会降级为纯文本编辑器。
三步完成代码项目接入Agent Space
第一步：安装CLI工具并验证Go版本
执行go version，确认输出中包含go1.21或更高版本。低于此版本会导致aw命令编译失败，且错误提示极其隐蔽，仅显示command not found。
第二步：初始化工作空间配置
在项目根目录下创建名为.aw.yaml的文件（注意开头是点号，不是下划线），内容至少包含：
name: my-web-api
environment:
type: docker
image: node:18-slim
第三步：启动并验证隔离环境
执行aw start → 等待终端输出✅ Workspace ready at http://localhost:3000 → 在浏览器打开该地址。如果页面显示“Cannot GET /”，说明Docker容器已成功拉起但应用未启动；若直接报错“Connection refused”，则environment.type字段拼写错误或镜像名称无效，需检查YAML缩进和冒号后空格。
不同项目类型推荐的运行模式
方法一：前端单页应用（React/Vue）
在.aw.yaml中设置environment.type: docker，并添加ports: ["3000:3000"]。这样本地浏览器访问http://localhost:3000就能实时预览热更新效果，无需额外配置反向代理。
方法二：Python数据处理脚本
改用environment.type: venv，并在同一文件中声明environment.requirements: requirements.txt。Agent Space会自动创建独立虚拟环境并安装依赖，彻底避免与系统Python或全局pip包发生冲突。
方法三：多服务联调项目（如前端+后端+数据库）
启用docker-compose.yml联动：在.aw.yaml中写入services:
- name: api
compose_file: docker-compose.api.yml
- name: db
compose_file: docker-compose.db.yml。Agent Space会按顺序启动所有服务，并自动注入环境变量打通网络。
代码变更后如何触发云端自动构建
在项目根目录下新建.aw.hooks.yaml，填入以下内容：
on_change:
- path: "src/**/*.ts"
run: "npx tsc --noEmit && echo 'TypeScript check passed'"
- path: "package.json"
run: "npm install --no-save"
保存后，只要修改任意.ts文件或更新package.json，Agent Space就会自动执行对应命令。注意：【hook命令必须是同步执行且返回0退出码，否则后续步骤会被阻断】。例如npm run dev这种长期运行的命令不能放在这里。
