agent space workspace 需显式绑定目录与逻辑项目，否则在 monorepo 或 git worktree 下会因 directory ≠ project 导致状态污染；可通过 .workspace 文件、agent-workspace link 或环境变量 aw_workspace_project/aw_workspace_worktree 三种方式手动关联，并用 agent-workspace context show 和 exec 验证三元组及文件加载是否正确。
☞☞☞AI 智能聊天, 问答助手, AI 智能搜索, 多模态理解力帮你轻松跨越从0到1的创作门槛☜☜☜
要让 Agent Space Workspace 正确识别并关联你本地的项目文件，不能只靠把代码扔进某个文件夹——它需要明确知道“这个目录属于哪个逻辑项目”，尤其在 monorepo 或 git worktree 场景下，【directory ≠ project】。直接用当前路径作唯一标识会导致多个子目录被当成不同项目，或同一仓库的多个 worktree 共享 session 数据，引发状态污染。
确认 workspace 根目录是否已初始化
进入你的目标项目目录（例如 ~/my-ai-app），运行：
```bash
ls -a | grep -E "^(\.agent|\.workspace|AGENTS\.md|MEMORY\.md)$"
```
如果没有任何输出，说明该目录尚未被识别为 workspace，需手动初始化。
执行：agent-workspace init
这会在当前目录生成 .workspace 文件，并自动推导 project 和 worktree 字段。若当前目录是 git 子模块或 monorepo 子路径，工具会向上查找最近的 .git 目录作为 worktree 根，再结合配置决定 project 名称。
手动绑定 project 与 directory 的三种方式
方法一：通过 .workspace 配置文件显式声明
在项目根目录创建或编辑 .workspace（YAML 格式），写入：
project: "my-ai-service"<br>worktree: "/Users/you/src/my-monorepo"<br>directory: "/Users/you/src/my-monorepo/packages/ai-service"
【必须确保 worktree 路径下存在 .git 目录，否则 agent 无法加载 git-aware 状态】
方法二：使用 agent-workspace CLI 关联已有项目
先确保你已在全局配置中设置了默认 project registry：agent-workspace config set registry.path ~/.agent-projects
然后在项目目录内运行：agent-workspace link --as my-ai-service
该命令会将当前 directory 注册到 registry，并生成符号链接 ~/.agent-projects/my-ai-service → /full/path/to/directory，后续所有 aw my-ai-service 调用都会精准定位。
方法三：在启动时动态指定（适用于临时调试）
不修改磁盘文件，直接运行：AW_WORKSPACE_PROJECT=my-ai-service AW_WORKSPACE_WORKTREE=/path/to/repo aw run
环境变量优先级高于 .workspace 文件，适合 CI/CD 或快速验证多分支行为。注意：此方式不会持久化，关闭终端即失效。
验证关联是否生效
第一步：检查 context 三元组是否正确解析
在项目目录中执行：agent-workspace context show
输出应类似：
directory: /Users/you/src/my-monorepo/packages/ai-service<br>worktree: /Users/you/src/my-monorepo<br>project: my-ai-service
第二步：触发一次最小工作流确认加载路径
运行：agent-workspace exec -- echo "Loaded $(cat AGENTS.md | head -n1)"
若成功打印出 # 我是客服助手小美 或类似首行内容，说明 workspace 已正确挂载项目文件，且 AGENTS.md 被识别为该 project 的人格入口。
第三步：检查 sandbox 是否合并（monorepo 场景关键验证）
进入另一个同仓库子目录（如 packages/core），运行：agent-workspace context show | grep project
输出应与上一步完全一致——【若显示不同 project 名，说明 worktree 推导失败，需检查 .git 位置或手动设置 worktree 字段】
