diff --git a/README.md b/README.md index d4befa81..3b2cbc27 100644 --- 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 ` 切换;`/model reset` 恢复默认 | | `/memory list` | 浏览知识库目录 | | `/memory search 关键词` | 搜索知识库 | diff --git a/README_EN.md b/README_EN.md index 06073041..a0ca0a06 100644 --- 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 ` | 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 ` — set model; `/model reset` — restore default | | `/memory list` | Browse knowledge tree | | `/memory search ` | Search knowledge base | diff --git a/docs/features/agent-teams.md b/docs/features/agent-teams.md new file mode 100644 index 00000000..e7817df9 --- /dev/null +++ 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 new file mode 100644 index 00000000..0d8ac033 --- /dev/null +++ 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 new file mode 100644 index 00000000..d0ec07a7 --- /dev/null +++ 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: ` 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 ` | 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 new file mode 100644 index 00000000..75dc86e9 --- /dev/null +++ b/docs/features/goal-loops.zh.md @@ -0,0 +1,56 @@ +# 目标循环(Goal Loops) + +设一个目标,MetaBot 让 Claude 跨多轮持续推进,直到目标达成。 + +## 功能 + +`/goal` 让你把"目标"交给 Claude,而不是单条指令。Agent 会**跨多轮**自动驱动:检查、重试、等待外部状态,达成条件时回来汇报(或者你主动叫停)。 + +飞书卡片会在多轮之间持续显示 `🎯 Goal: ` 徽标,你随时知道 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 index 74ed7cd1..8a1899d5 100644 --- 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 ` | 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 ` | 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 index 33f0deb5..2f8c9412 100644 --- 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 index 5f3c6d63..0d9b55e6 100644 --- 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