工作区技能

通过为每个工作区配置独立代理、隔离内存及 Swarm 风格的代理编排机制，统一管理多个项目工作区。

/workplace 命令（Telegram / Slash）

支持父子层级导航，可逐级向下钻取。

• /workplace 或 /workplace list → 显示顶层视图：以按钮形式列出父级工作区与独立工作区。父级工作区标注子项数量 (N)；当前工作区以 ✓ 标记。
• 点击父级按钮 → 进入其子级列表，显示所有子级按钮 + “Use parent” + “← Back”。
• /workplace → 若目标为独立工作区或子工作区，则直接切换；若为目标为含子项的父工作区，则展示其子级列表（即钻取）。
• /workplace parent:child → 使用冒号语法直接切换（例如：log-stream:logstream）。
• /workplace status → 显示当前工作区卡片，含父工作区、关联工作区、代理列表、部署环境等信息。
• /workplace agents → 列出当前工作区所有代理，并提供启动/停止按钮。

冒号语法

/workplace log-stream:logstream 会先按名称解析父工作区，再在其下查找指定子工作区。该语法支持免菜单导航的快速切换。

上下文切换

当用户通过按钮点击、名称或冒号语法切换工作区时，系统执行以下操作：

1. 更新 ~/.openclaw/workspace/.workplaces/current.json，写入所选工作区的 UUID 和路径
2. 更新 registry.json 中对应条目的 lastActive 字段
3. 加载新工作区下的 .workplace/config.json 以获取上下文信息
4. 发送确认消息：包含工作区名称、路径、父工作区（如存在）、关联工作区、代理列表
5. 此后该会话中的所有后续消息均需感知并绑定当前激活的工作区上下文

任何工作区操作启动前，均须读取 current.json 以确定当前激活的工作区。

完整按钮布局、回调路由逻辑及平台降级策略详见 telegram-ui.md。

速查表

架构设计

注册中心（Registry）

中央注册中心位于 ~/.openclaw/workspace/.workplaces/：

• registry.json — 记录所有已知工作区，含 UUID、路径、主机名、关联关系等
• current.json — 记录当前激活的工作区

单工作区结构

每个项目根目录下拥有一个 .workplace/ 目录：

.workplace/
├── config.json          # UUID、名称、路径、主机名、关联工作区、父工作区
├── agents/*.md          # 代理角色定义（kernel.md 始终存在）
├── memory/              # 隔离式每日日志（YYYY-MM-DD.md）
├── skills/              # 工作区专属技能（由用户通过 git 维护）
├── chat.md              # 代理间通信记录
├── structure.json       # 自动扫描生成的文件树结构
├── full-tree.md         # 完整树状结构（含父工作区 + 同主机名关联工作区）
├── process-status.json  # 代理运行时状态与错误信息
└── deploy/              # 部署文档：dev.md、main.md、pre.md

工作区识别机制

• 任意含 .git/ 目录的路径均视为潜在工作区
• Git 子模块被识别为嵌套工作区
• 父工作区自动从上级目录推导得出
• 亦可通过 workplace link 手动建立关联

典型工作流

初始化工作区

1. 运行 scripts/init_workplace.sh [--name ] [--desc ]
2. 对已有项目：扫描文件结构、读取 *.md 文件、分析项目类型、推荐代理配置
3. 对空目录：提示输入项目名称、描述、语言/框架、所需角色等信息
4. 自动生成 .workplace/ 目录结构，注册至中央注册中心，并设为当前工作区
5. 完整初始化流程详见 init-guide.md

代理系统

代理定义为 .workplace/agents/ 下的 .md 文件，含 YAML 前置元数据（name、role、triggers、handoff_to）。通过 sessions_spawn 启动代理，其系统提示词由代理定义与工作区上下文共同构建。

• 代理创建、Swarm 式交接与运行时细节详见 agent-system.md

代理间通信

代理通过 chat.md 进行结构化消息通信。Rust 编写的文件监听服务实时监控该文件变更，并将解析后的消息以 JSON 行格式输出。

• 消息格式规范详见 chat-protocol.md

Rust 文件监听服务（File-Watcher Server）

二进制文件位于 assets/bin/workplace-server-{os}-{arch}，源码构建方式为 scripts/build.sh。

# 启动指定项目的工作区监听服务
workplace-server /path/to/project

# 服务将每个新增的 chat.md 消息以 JSON 行格式输出至 stdout
{"timestamp":"...","sender":"coder","recipient":"reviewer","broadcast":[],"message":"...","line_number":1}

导出与导入

• ZIP 格式：完整打包 .workplace/ 目录（默认排除 memory/）
• JSON 格式：仅导出配置、代理定义与部署文档，形成轻量可移植清单
• 导入时生成全新 UUID，避免冲突

聊天界面（Telegram / Discord）

在支持内联按钮的平台（如 Telegram / Discord）上：workplace list 显示可点击的工作区切换器；workplace agents 为每个代理提供独立的启动/停止按钮；workplace deploy 显示各部署环境按钮。

消息格式、按钮组件与回调处理逻辑详见 telegram-ui.md。

降级方案：在不支持按钮的平台（如 WhatsApp、Signal）上，以编号文本列表形式呈现。

IDE 集成

将工作区上下文同步至外部编码工具：

• Cursor → .cursor/rules/workplace.mdc（含前置元数据的 MDC 文件）
• Claude Code → CLAUDE.md（Markdown 格式，基于标记增量更新）
• OpenCode → opencode.jsonc 中的 instructions 字段

运行 workplace sync all 可批量更新所有已检测到的 IDE；也可指定单一目标，如：workplace sync cursor。

实现细节详见 ide-sync.md。

脚本清单

Supermemory 集成

每个工作区以其 UUID 作为 containerTag 执行 Supermemory 操作：

• 内核代理负责保存结构摘要与项目事实
• 所有工作区记忆均通过 containerTag 实现严格隔离
• 支持跨会话的项目状态感知能力

命令详情

完整命令参考（含示例）详见 commands.md。