docs: document /goal loops and Agent Teams (#276)

floodsung · Flood Sung · web-flow · commit 17ef6bd17a4a · 2026-05-14T09:13:46.000Z
* feat(installer): allow custom install directory via --dir / -Dir flag

install.sh and install.ps1 previously hardcoded the install path to
$HOME/metabot. Add a CLI flag (and matching PowerShell parameter) plus
an interactive prompt so users can install MetaBot anywhere.

- Priority: --dir / -Dir &gt; METABOT_HOME env var &gt; prompt &gt; default.
- Tilde expansion + absolute-path validation; refuses to clobber
  $HOME / system roots.
- Persists METABOT_HOME to ~/.bashrc / ~/.zshrc (Linux/macOS) or
  user-level env (Windows) when non-default, so the mm/mb/metabot
  CLIs can locate the install in new shells.

* fix(codex): show model metadata in cards

* fix(codex): mirror skills and avoid bwrap sandbox

* fix(codex): tolerate agents deployment failures

* fix(codex): install bundled skills when user cache is empty

* docs: explain Codex skill migration

* docs: document /goal loops and Agent Teams

- README_EN.md / README.md: add Core Components rows for Persistent
  Sessions &amp; Goal Loops and Agent Teams, new Example Prompts sections,
  and /goal row in the Chat Commands table.
- docs/features/goal-loops.{md,zh.md}: new feature page covering
  Claude-native Stop hook + fast-model evaluator and MetaBot's
  persistent-executor role.
- docs/features/agent-teams.{md,zh.md}: new feature page describing
  the runtime team experience; honest about current Team-panel
  limitations (SDK hooks not firing yet, activity surfaces in the
  agent activity card).
- docs/usage/chat-commands.{md,zh.md}: add /goal row with link to the
  new feature page.
- mkdocs.yml: add both pages to the en and zh nav blocks under
  Features, adjacent to MetaSkill.

---------

Co-authored-by: Flood Sung &lt;floodsung@xvirobotics.ai&gt;
diff --git a/README.md b/README.md
@@ -175,6 +175,8 @@ MetaBot 支持 4 种方式与你的 Agent 团队交互：
 | 组件 | 一句话说明 |
 |------|-----------|
 | **三引擎内核** | 每个 Bot 独立选 Claude Code / Kimi Code / Codex CLI — 完整工具链（Read/Write/Edit/Bash/Glob/Grep/WebSearch/MCP），自主模式运行 |
+| **常驻会话与目标循环** | 每个会话一个常驻 Claude 进程 — `/goal` 让 Agent 在多轮之间持续自驱直到目标达成；团队成员和后台任务跨轮存活 |
+| **Agent 团队（运行时）** | 主导 Agent 并行派遣专家队友，互相路由任务、汇总结果 —— 全部在一个飞书会话中完成 |
 | **CC 原生调度** | 直接用 Claude Code 内置的 `CronCreate` / `/loop` —— 即开即用，会话内最简单 |
 | **MetaMemory** | 内嵌 SQLite 知识库，全文搜索，Web UI，变更自动同步到飞书知识库 |
 | **IM Bridge** | 飞书、Telegram、微信（含手机端）对话任意 Agent，流式卡片 + 工具调用追踪 |
@@ -241,6 +243,21 @@ MetaBot 支持 4 种方式与你的 Agent 团队交互：
 > （`cp src/skills/metaschedule/SKILL.md ~/.claude/skills/metaschedule/`），
 > 就能用 `mb schedule cron` / HTTP API 提交到 MetaBot 服务端调度器。
 
+### Agent 团队 — 运行时协作
+
+```
+你来当主导工程师。并行派出一个前端专家和一个后端专家：
+前端负责 React UI 改造，后端加上新的 /api/reports 接口，
+你负责 review 两边的 PR，全部通过后再合并。
+```
+
+### 目标循环
+
+```
+/goal PR #123 的 CI 全绿、部署成功。
+每 10 分钟检查一次，搞定后告诉我。
+```
+
 ### MetaSkill — Agent 工厂（可选）
 
 `/metaskill` 默认不装。先启用：`cp -r src/skills/metaskill ~/.claude/skills/`，然后：
@@ -406,6 +423,7 @@ MetaBot 以 `bypassPermissions` 模式运行 Claude Code — 无交互式确认
 | `/reset` | 清除会话 |
 | `/stop` | 中止当前任务 |
 | `/status` | 查看会话状态（含当前模型） |
+| `/goal <条件>` | 设置目标，Agent 跨多轮持续推进直到达成。`/goal clear` 停止 |
 | `/model` | 查看当前模型；`/model list` 查看可用模型；`/model <name>` 切换；`/model reset` 恢复默认 |
 | `/memory list` | 浏览知识库目录 |
 | `/memory search 关键词` | 搜索知识库 |
diff --git a/README_EN.md b/README_EN.md
@@ -171,6 +171,8 @@ Full-featured browser-based chat interface. Access at `https://your-server/web/`
 | Component | Description |
 |-----------|-------------|
 | **Triple Engine Kernel** | Each bot independently chooses Claude Code / Kimi Code / Codex CLI — full tool stack (Read/Write/Edit/Bash/Glob/Grep/WebSearch/MCP) in autonomous mode |
+| **Persistent Sessions & Goal Loops** | One Claude process per chat — `/goal` keeps the agent auto-driving across turns until a condition is met; teammates and background tasks survive between turns |
+| **Agent Teams** | A lead agent spawns specialist teammates in parallel, routes tasks between them, and aggregates results — all in one Feishu chat |
 | **CC-Native Scheduling** | Use Claude Code's built-in `CronCreate` and `/loop` directly — zero MetaBot setup, runs in-session |
 | **MetaMemory** | Embedded SQLite knowledge store with full-text search, Web UI, auto-syncs to Feishu Wiki |
 | **IM Bridge** | Chat with any agent from Feishu, Telegram, or WeChat (including mobile). Streaming cards + tool call tracking |
@@ -240,6 +242,21 @@ summarize the top 5 stories, and save the summary to MetaMemory.
 > then use `mb schedule cron` / the HTTP API to submit jobs to MetaBot's
 > persistent scheduler.
 
+### Agent Teams — Runtime
+
+```
+Act as a lead engineer. Spawn a frontend specialist and a backend specialist
+in parallel: the frontend handles the React UI changes, the backend adds the
+new /api/reports endpoint, and you review both PRs before merging.
+```
+
+### Goal Loops
+
+```
+/goal The CI for PR #123 is green and the deploy completes successfully.
+Check every 10 minutes and report back when done.
+```
+
 ### MetaSkill — Agent Factory (opt-in)
 
 `/metaskill` is not installed by default. Enable it first:
@@ -409,6 +426,7 @@ MetaBot runs Claude Code in `bypassPermissions` mode — no interactive approval
 | `/reset` | Clear session |
 | `/stop` | Abort current task |
 | `/status` | Session info (includes current model) |
+| `/goal <condition>` | Set a goal the agent keeps pursuing across turns. `/goal clear` to stop |
 | `/model` | Show current engine/model; `/model list` — available engines/models; `/model claude`, `/model kimi`, or `/model codex` — switch engine; `/model <name>` — set model; `/model reset` — restore default |
 | `/memory list` | Browse knowledge tree |
 | `/memory search <query>` | Search knowledge base |
diff --git a/docs/features/agent-teams.md b/docs/features/agent-teams.md
@@ -0,0 +1,52 @@
+# Agent Teams
+
+A lead agent spawns specialist teammates in parallel, routes tasks between them, and aggregates results — all inside a single Feishu chat.
+
+## What It Does
+
+Agent Teams is the **runtime** team experience inside a single chat session:
+
+- A **lead agent** receives your request and decides what specialists are needed.
+- The lead spawns **teammates** (frontend, backend, reviewer, …) via the `Agent` tool. Teammates run as separate sub-agents under the same chat process.
+- Teammates can be addressed across turns: the lead routes tasks via `SendMessage`, asks teammates to report back, and aggregates the results.
+- Everything happens in one Feishu chat — you talk to the lead, the lead talks to the team.
+
+This is the runtime counterpart to [MetaSkill](metaskill.md): MetaSkill *generates* an agent team configuration (CLAUDE.md / AGENTS.md + skills), while Agent Teams *runs* it.
+
+## Usage
+
+Prompt the lead agent to spawn teammates. You don't need a special command — just describe the team and the work:
+
+```
+Act as a lead engineer. Spawn a frontend specialist and a backend specialist
+in parallel: the frontend handles the React UI changes, the backend adds the
+new /api/reports endpoint, and you review both PRs before merging.
+```
+
+```
+Spawn a researcher and a writer teammate. The researcher gathers everything
+we have on competitor X's pricing strategy from MetaMemory and the web.
+The writer turns it into a one-pager. Hand off when done.
+```
+
+If your bot already has a generated team (via `/metaskill`), the orchestrator agent in that team is your lead — just describe the goal.
+
+## How It Works
+
+- **Persistent process per chat.** Teammates spawned in turn 1 are still addressable in turn N hours later, because each chat has one long-lived Claude process (see [How it works in CLAUDE.md](https://github.com/xvirobotics/metabot/blob/main/CLAUDE.md#persistent-claude-process-per-chat-stage-4--opt-in)). Without this, every turn would spawn a fresh subprocess and tear down all teammates.
+- **Agent tool spawns teammates.** The lead uses Claude's native `Agent` tool with a `team_name=` parameter to start a teammate. Teammates inherit the same working directory and tools.
+- **Cross-agent messaging.** Teammates and the lead use `SendMessage` to exchange messages. Replies are queued and delivered when the recipient is ready.
+- **Background activity surfacing.** Teammate progress between user turns shows up as a coalesced "Agent activity" card in Feishu (30-second debounce, so you don't get spammed during fast back-and-forth).
+
+## Current Limitations
+
+- **Team panel UX is coming soon.** A dedicated `🧑‍🤝‍🧑 Team` panel showing each teammate with a working/idle status icon and a shared task list is implemented in the card renderer, but the upstream SDK hooks that populate it (`TaskCreated` / `TaskCompleted` / `TeammateIdle`) do not fire reliably yet. Today, teammate activity surfaces in the existing **agent activity card** during the run.
+- **Claude engine only.** Teammate spawning relies on Claude's native `Agent` tool. Kimi and Codex bots don't support Agent Teams yet.
+- **One lead per chat.** The chat session has one process, so one lead agent. Use separate Feishu chats (or [peers](peers.md)) to run multiple independent teams.
+- **Budget is shared.** All teammates run inside the same chat's token budget. Heavy parallel work counts against `maxBudgetUsd`.
+
+## See Also
+
+- [MetaSkill](metaskill.md) — generate a team configuration before running it
+- [Goal Loops](goal-loops.md) — give the team a multi-turn objective
+- [Peers](peers.md) — run teams on separate MetaBot instances and route between them
diff --git a/docs/features/agent-teams.zh.md b/docs/features/agent-teams.zh.md
@@ -0,0 +1,51 @@
+# Agent 团队
+
+主导 Agent 并行派遣专家队友，互相路由任务、汇总结果 —— 全部在一个飞书会话中完成。
+
+## 功能
+
+Agent 团队是单个会话内的**运行时**团队体验：
+
+- **主导 Agent**接到你的需求，决定需要哪些专家。
+- 主导 Agent 通过 `Agent` 工具派遣**队友**（前端、后端、Reviewer 等）。队友以子 Agent 形式运行在同一个会话进程下。
+- 队友跨多轮可寻址：主导 Agent 用 `SendMessage` 路由任务、请队友汇报，并汇总结果。
+- 所有交互都在一个飞书会话中 —— 你和主导 Agent 对话，主导 Agent 协调团队。
+
+这是 [MetaSkill](metaskill.md) 的运行时对应：MetaSkill *生成* Agent 团队的配置（CLAUDE.md / AGENTS.md + skills），Agent 团队负责*运行*它。
+
+## 用法
+
+让主导 Agent 派出队友即可，不需要特殊命令 —— 把团队和工作描述出来：
+
+```
+你来当主导工程师。并行派出一个前端专家和一个后端专家：
+前端负责 React UI 改造，后端加上新的 /api/reports 接口，
+你负责 review 两边的 PR，全部通过后再合并。
+```
+
+```
+派出一个研究员和一个写手队友。研究员从 MetaMemory 和网络
+收集竞品 X 的定价策略；写手整理成一页纸。完成后交付。
+```
+
+如果你的 Bot 已经通过 `/metaskill` 生成了团队，里面的 orchestrator 就是主导 Agent —— 直接描述目标即可。
+
+## 工作原理
+
+- **每个会话一个常驻进程。**第 1 轮派出的队友，几小时后第 N 轮仍可寻址。原因是每个会话有一个长生命周期的 Claude 进程（见 [CLAUDE.md 中的说明](https://github.com/xvirobotics/metabot/blob/main/CLAUDE.md#persistent-claude-process-per-chat-stage-4--opt-in)）。如果没有这个机制，每轮都重新启动子进程，所有队友会被销毁。
+- **Agent 工具派遣队友。**主导 Agent 用 Claude 原生的 `Agent` 工具加 `team_name=` 参数派出队友。队友继承同样的工作目录和工具集。
+- **跨 Agent 消息。**队友和主导 Agent 通过 `SendMessage` 交换消息。回复会排队，接收方就绪后投递。
+- **后台活动展示。**用户轮之间的队友进度，会在飞书以合并后的"Agent activity"卡片呈现（30 秒去抖，避免快速交互时刷屏）。
+
+## 当前限制
+
+- **专属团队面板即将上线。**专门的 `🧑‍🤝‍🧑 Team` 面板（队友列表带忙/闲图标 + 共享任务列表）渲染逻辑已经写好，但上游 SDK 的 hooks（`TaskCreated` / `TaskCompleted` / `TeammateIdle`）目前还不稳定触发。当前队友活动展示在运行期的**Agent activity 卡片**中。
+- **仅 Claude 引擎。**队友派遣依赖 Claude 原生 `Agent` 工具，Kimi 和 Codex Bot 暂不支持 Agent 团队。
+- **每个会话一个主导 Agent。**单会话单进程，只能有一个主导 Agent。需要并行运行多个独立团队时，用不同的飞书会话（或 [peers](peers.md)）。
+- **预算共享。**所有队友共享同一个会话的 token 预算，重并行任务会快速计入 `maxBudgetUsd`。
+
+## 相关
+
+- [MetaSkill](metaskill.md) — 先用它生成团队配置，再运行
+- [目标循环](goal-loops.md) — 给团队一个跨多轮的目标
+- [Peers 联邦](peers.md) — 把团队跑在不同 MetaBot 实例上，跨实例路由
diff --git a/docs/features/goal-loops.md b/docs/features/goal-loops.md
@@ -0,0 +1,56 @@
+# Goal Loops
+
+Set a goal condition; MetaBot keeps Claude working across turns until the goal is met.
+
+## What It Does
+
+`/goal` lets you hand Claude an objective rather than a single instruction. The agent keeps pursuing the goal across **multiple turns** — checking, retrying, waiting on external state — and reports back when the condition is satisfied (or when you tell it to stop).
+
+The Feishu card shows a persistent `🎯 Goal: <condition>` badge across turns, so you always know what the agent is chasing.
+
+## Usage
+
+Send `/goal` followed by the condition you want satisfied:
+
+```
+/goal The CI for PR #123 is green and the deploy completes successfully.
+Check every 10 minutes and report back when done.
+```
+
+```
+/goal All open Linear tickets in the INGEST project are either resolved
+or assigned to a human. Recheck every 30 minutes.
+```
+
+Other forms:
+
+| Command | Effect |
+|---------|--------|
+| `/goal <condition>` | Set or replace the active goal |
+| `/goal` | Query the current goal (no mutation) |
+| `/goal clear` (or `stop` / `off` / `reset` / `none` / `cancel`) | Clear the active goal |
+
+## How It Works
+
+`/goal` is a **Claude Code native command** — the loop machinery lives inside Claude Code itself:
+
+1. Claude registers a session-scoped **Stop hook** when the goal is set.
+2. When a turn finishes, the Stop hook runs a fast-model evaluator against the goal condition.
+3. If the goal is **not yet met**, the evaluator queues another turn automatically. If it **is** met, the loop ends and Claude reports the result.
+
+MetaBot's contribution is the runtime that makes this work over Feishu:
+
+- The **persistent Claude process per chat** (one long-lived SDK session per `chatId`) is what keeps the Stop hook alive between user turns. Without it, every turn spawned a fresh subprocess and killed any in-flight hooks. This runs by default — no configuration needed.
+- The Feishu card mirrors the goal condition into a persistent badge so the user can see what's being pursued.
+
+## Limits
+
+- Auto-driven turns count toward the bot's token budget (`maxBudgetUsd`) and turn limit (`maxTurns`) just like manual turns.
+- One active goal per chat session. Setting a new goal replaces the previous one.
+- Use `/stop` to abort the current turn; use `/goal clear` to stop the loop entirely.
+- Goals are scoped to a single chat (`chatId`); they don't persist after `/reset`.
+
+## See Also
+
+- [Agent Teams](agent-teams.md) — combine a goal with parallel teammates
+- [Chat Commands](../usage/chat-commands.md) — full command reference
diff --git a/docs/features/goal-loops.zh.md b/docs/features/goal-loops.zh.md
@@ -0,0 +1,56 @@
+# 目标循环（Goal Loops）
+
+设一个目标，MetaBot 让 Claude 跨多轮持续推进，直到目标达成。
+
+## 功能
+
+`/goal` 让你把"目标"交给 Claude，而不是单条指令。Agent 会**跨多轮**自动驱动：检查、重试、等待外部状态，达成条件时回来汇报（或者你主动叫停）。
+
+飞书卡片会在多轮之间持续显示 `🎯 Goal: <condition>` 徽标，你随时知道 Agent 在追什么。
+
+## 用法
+
+发 `/goal` 加目标条件：
+
+```
+/goal PR #123 的 CI 全绿、部署成功。
+每 10 分钟检查一次，搞定后告诉我。
+```
+
+```
+/goal Linear INGEST 项目下所有 open ticket 都已解决或分派给人。
+每 30 分钟复查一次。
+```
+
+其他形式：
+
+| 命令 | 效果 |
+|------|------|
+| `/goal <条件>` | 设置或替换当前目标 |
+| `/goal` | 查询当前目标（不修改） |
+| `/goal clear`（或 `stop` / `off` / `reset` / `none` / `cancel`） | 清除当前目标 |
+
+## 工作原理
+
+`/goal` 是 **Claude Code 原生命令**，循环机制本身跑在 Claude Code 内部：
+
+1. 设置目标时，Claude 注册一个会话级 **Stop hook**。
+2. 每轮结束时，Stop hook 调用快速模型评估目标是否达成。
+3. **未达成**则自动排队下一轮；**已达成**则结束循环并汇报结果。
+
+MetaBot 的贡献是让这套机制能跨飞书消息工作：
+
+- **每个会话一个常驻 Claude 进程**（一个长生命周期的 SDK 会话 per `chatId`），这是 Stop hook 跨用户轮存活的前提。没有它的话，每轮都重新启动子进程，hook 会被杀掉。该机制默认开启，无需配置。
+- 飞书卡片把目标条件镜像成持久徽标，让用户看到 Agent 在追什么。
+
+## 限制
+
+- 自动驱动的轮次和手动轮次一样，计入 Bot 的 token 预算（`maxBudgetUsd`）和轮次上限（`maxTurns`）。
+- 每个会话只能有一个活跃目标。再次设置会替换原目标。
+- `/stop` 中止当前轮次；`/goal clear` 完全停止循环。
+- 目标作用域是单个会话（`chatId`），`/reset` 后不保留。
+
+## 相关
+
+- [Agent 团队](agent-teams.md) — 把目标和并行队友组合使用
+- [聊天命令](../usage/chat-commands.md) — 完整命令参考
diff --git a/docs/usage/chat-commands.md b/docs/usage/chat-commands.md
@@ -9,6 +9,7 @@ Commands you can send to MetaBot in Feishu or Telegram.
 | `/reset` | Clear session — starts a fresh conversation |
 | `/stop` | Abort the currently running task |
 | `/status` | Show session info (session ID, working directory) |
+| `/goal <condition>` | Set a goal the agent keeps pursuing across turns. `/goal clear` to stop. See [Goal Loops](../features/goal-loops.md) |
 | `/memory list` | Browse MetaMemory knowledge tree |
 | `/memory search <query>` | Search MetaMemory knowledge base |
 | `/sync` | Trigger MetaMemory → Feishu Wiki sync |
diff --git a/docs/usage/chat-commands.zh.md b/docs/usage/chat-commands.zh.md
@@ -9,6 +9,7 @@
 | `/reset` | 清除会话 — 开始全新对话 |
 | `/stop` | 中止当前任务 |
 | `/status` | 查看会话信息（会话 ID、工作目录） |
+| `/goal <条件>` | 设置目标，Agent 跨多轮持续推进直到达成。`/goal clear` 停止。参见 [目标循环](../features/goal-loops.md) |
 | `/memory list` | 浏览 MetaMemory 知识库目录 |
 | `/memory search 关键词` | 搜索 MetaMemory 知识库 |
 | `/sync` | 触发 MetaMemory → 飞书知识库同步 |
diff --git a/mkdocs.yml b/mkdocs.yml
@@ -73,6 +73,8 @@ plugins:
               - 安全: concepts/security.md
             - 功能:
               - MetaSkill: features/metaskill.md
+              - 目标循环: features/goal-loops.md
+              - Agent 团队: features/agent-teams.md
               - MetaMemory: features/metamemory.md
               - Web UI: features/web-ui.md
               - Peers 联邦: features/peers.md
@@ -125,6 +127,8 @@ nav:
     - Security: concepts/security.md
   - Features:
     - MetaSkill: features/metaskill.md
+    - Goal Loops: features/goal-loops.md
+    - Agent Teams: features/agent-teams.md
     - MetaMemory: features/metamemory.md
     - Web UI: features/web-ui.md
     - Peers Federation: features/peers.md
