From daa2c8b9aca4a9035a72d05d2871ef2cb959952f Mon Sep 17 00:00:00 2001
From: mateaix <57164338+mateaix@users.noreply.github.com>
Date: Sun, 26 Jul 2026 11:58:59 +0800
Subject: [PATCH] =?UTF-8?q?docs:=202.0.0=20release=20documentation=20?=
=?UTF-8?q?=E2=80=94=20agent=20teams=20guide,=20feature=20doc=20updates,?=
=?UTF-8?q?=20README=20and=20site=20refresh?=
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit
---
README.md | 18 +-
README_zh.md | 18 +-
assets/architecture-biz-en.svg | 8 +-
assets/architecture-biz-zh.svg | 8 +-
assets/architecture-tech-en.svg | 6 +-
assets/architecture-tech-zh.svg | 6 +-
.../src/main/resources/docs/en/channels.md | 30 +++-
.../src/main/resources/docs/en/chat.md | 18 ++
.../src/main/resources/docs/en/index.md | 3 +
.../src/main/resources/docs/en/models.md | 9 +
.../src/main/resources/docs/en/releases.md | 1 +
.../src/main/resources/docs/en/roadmap.md | 48 +++---
.../src/main/resources/docs/en/security.md | 11 ++
.../src/main/resources/docs/en/skills.md | 38 ++++-
.../src/main/resources/docs/en/teams.md | 159 ++++++++++++++++++
.../main/resources/docs/en/wecom-tuning.md | 15 ++
.../src/main/resources/docs/en/wiki.md | 6 +
.../src/main/resources/docs/en/workspaces.md | 15 ++
.../src/main/resources/docs/zh/channels.md | 30 +++-
.../src/main/resources/docs/zh/chat.md | 18 ++
.../src/main/resources/docs/zh/index.md | 3 +
.../src/main/resources/docs/zh/models.md | 9 +
.../src/main/resources/docs/zh/releases.md | 1 +
.../src/main/resources/docs/zh/roadmap.md | 44 ++---
.../src/main/resources/docs/zh/security.md | 11 ++
.../src/main/resources/docs/zh/skills.md | 38 ++++-
.../src/main/resources/docs/zh/teams.md | 159 ++++++++++++++++++
.../main/resources/docs/zh/wecom-tuning.md | 15 ++
.../src/main/resources/docs/zh/wiki.md | 6 +
.../src/main/resources/docs/zh/workspaces.md | 15 ++
30 files changed, 698 insertions(+), 68 deletions(-)
create mode 100644 mateclaw-server/src/main/resources/docs/en/teams.md
create mode 100644 mateclaw-server/src/main/resources/docs/zh/teams.md
diff --git a/README.md b/README.md
index 09e12138..2f55171b 100644
--- a/README.md
+++ b/README.md
@@ -81,6 +81,9 @@ Same brain. Same memory. Same tools. Different doors.
### Digital employees, not chatbots
You hire coworkers, not chat boxes. Each one has a **Role**, a **Goal**, a **Backstory**, a pixel-art avatar, and a color of their own — five career templates ship ready (Product Researcher · Customer Support · Knowledge Curator · Data Analyst · Executive Assistant). **ReAct** drives iterative reasoning, **Plan-and-Execute** decomposes complex multi-step work, employees can delegate to one another in parallel. Dynamic context pruning, smart truncation, stale-stream cleanup — the boring stuff that makes long conversations actually work.
+### Agent Teams (2.0.0+)
+One lead, a crew of employees, one **shared task board**. Tell the lead a goal and it breaks the goal into tasks on the board (`blockedBy` declares dependencies); the dispatch engine hands tasks to members in parallel, prerequisite results hand off to downstream tasks automatically, and settled results are announced back to the lead for synthesis. Execution leases + heartbeats eliminate double execution, **cancel actually interrupts** a running member session, and sensitive tasks park at `in_review` for a human. Deliverables (docx / pptx / xlsx / pdf) register on tasks for download, timelines record everything, and you can jump into any member's child conversation to watch it execute word by word. A Plan-Execute lead hands its **whole plan over to the board** — a lead that can plan turns planning into orchestration.
+
### Knowledge & memory
- **LLM Wiki** — raw materials digest into linked pages with citations; the **hot cache** auto-injects into every employee's system prompt. **Transformations engine** (1.3.0+) turns the Wiki from a search index into a processing pipeline
- **Workspace memory** — `AGENTS.md`, `SOUL.md`, `PROFILE.md`, `MEMORY.md`, daily notes
@@ -203,7 +206,7 @@ Desktop binaries ship via [GitHub Releases](https://github.com/mateaix/mateclaw/
| Layer | Technology |
|---|---|
| Backend | Spring Boot 3.5 · Spring AI Alibaba 1.1 · MyBatis Plus · Flyway |
-| Digital Employee Runtime | StateGraph · ReAct + Plan-Execute · Role / Goal / Backstory · LESSONS self-evolution |
+| Digital Employee Runtime | StateGraph · ReAct + Plan-Execute · Role / Goal / Backstory · LESSONS self-evolution · Team task board (2.0.0+) |
| Orchestration | Workflow (7 step modes · Pebble DSL) · Triggers (6 pattern types · event governance) · Wiki Transformations (1.3.0+) |
| Capability Extension | SKILL.md packages · MCP (stdio / SSE / HTTP · per-agent binding) · ACP bridge (Claude Code / Codex) |
| Database | H2 (dev) · MySQL 8.0+ (prod) |
@@ -220,6 +223,19 @@ Full docs at **[claw.mate.vip/docs](https://claw.mate.vip/docs)** — setup, arc
## Roadmap
+**v2.0.0 (shipped 2026-07-26)** — from "one person who gets things done" to "a team that collaborates": **Agent Teams** become a standing roster around a shared task board:
+
+- **Agent teams and a shared task board** — teams / roles (lead · member · reviewer), an eight-status kanban, `blockedBy` dependency orchestration, member-level parallel dispatch, automatic prerequisite hand-off, settled results waking the lead; the Teams page ships an event-driven live board + activity banner + task timelines + deliverable downloads + manual task creation
+- **An execution chain hardened for long tasks** — execution leases + runtime heartbeats against double execution, cancel that actually interrupts, `in_review` approval gates, retry for failed/stale
+- **Plan-Execute plans hand over to the board** — steps become tasks, dependencies become parallelism, a parked-plan resume gate synthesizes deterministically
+- **Workspace isolation fully sealed** — channel-scoped conversation ids; same-named skills coexist per workspace with conversation-scoped runtime resolution
+- **Channel experience** — magic commands on every channel (`/new` `/clear` `/status` `/stop` `/model` `/help`), WeCom's event-driven progress bubble (live tool trace + per-stage rolling narration)
+- **Server-side rewind / regenerate** · **explainable auto-approval misses** (reason codes on audit rows + one-click grant creation) · **policy-driven LLM error recovery** (overload vs rate-limit split · `Retry-After`-aware backoff · provider TTL readmission)
+
+Plus: in-chat attachment preview (pdf / docx / xlsx / html / text), single-source SKILL.md + console bundle-file management, the optional Mem0 plugin memory provider, and the knowledge-graph relation schema whitelist.
+
+Full story in the [v2.0.0 release notes](https://claw.mate.vip/docs/en/releases/2.0.0).
+
**v1.8.0 (shipped 2026-07-12)** — the employee turns *outward and does a whole job*: **Content Studio**, the first flagship scene built end-to-end on MateClaw's own primitives:
- **Content Studio — one sentence to a publishable post** — a seeded "Content Studio" employee runs pick-topic → research → draft → illustrate → de-AI → layout → deliver. **WeChat Official Account (公众号)** image-text articles (inline-style HTML → draft box) and **Xiaohongshu (小红书)** image-first notes (≥3 vertical 3:4 cards + online preview) ship first-class
diff --git a/README_zh.md b/README_zh.md
index 69aefcaa..63240396 100644
--- a/README_zh.md
+++ b/README_zh.md
@@ -81,6 +81,9 @@ MateClaw 的 **LLM Wiki** 把它消化成结构化页面，页面之间自己长
### 数字员工，不是聊天机器人
你雇佣员工，不是开聊天框。每位有**角色**、**目标**、**背景故事**，像素艺术头像、专属配色——5 个职业模板（产品研究员 · 客户支持 · 知识管理员 · 数据分析师 · 行政助理）开箱可用。**ReAct** 做迭代推理，**Plan-and-Execute** 做复杂多步任务，员工之间可以并行委派。动态上下文裁剪、智能截断、僵死流清理——让长对话真正能用的那些"不起眼"的基础设施。
+### 团队协作（2.0.0+）
+一个 Lead 带一群员工，围着一块**共享任务板**干活。你对 Lead 说一句目标，它拆成任务上板（`blockedBy` 声明依赖）；派发引擎把任务并行分给成员，前置结果自动传给下游，完成结果自动通报回 Lead 汇总。执行租约 + 心跳杜绝双重执行，**取消即中断**正在跑的成员会话，敏感任务停在 `in_review` 等人批。交付物（docx / pptx / xlsx / pdf）登记到任务可下载，任务时间线记录全程，还能跳进任意成员的子会话看它逐字执行。Plan-Execute 型 Lead 的计划**整体移交任务板**——会规划的 Lead，规划能力就是编排能力。
+
### 知识与记忆
- **LLM Wiki** — 原始材料消化成有链接、带引用的结构化页面；**热点缓存**自动注入到员工的 system prompt。**加工器引擎**（1.3.0+）把 Wiki 从"搜索索引"升级为"处理流水线"
- **工作区记忆** — `AGENTS.md` / `SOUL.md` / `PROFILE.md` / `MEMORY.md` / 每日笔记
@@ -203,7 +206,7 @@ mateclaw/
| 层次 | 技术 |
|---|---|
| 后端 | Spring Boot 3.5 · Spring AI Alibaba 1.1 · MyBatis Plus · Flyway |
-| 数字员工运行时 | StateGraph · ReAct + Plan-Execute · 角色 / 目标 / 背景故事 · LESSONS 自我进化 |
+| 数字员工运行时 | StateGraph · ReAct + Plan-Execute · 角色 / 目标 / 背景故事 · LESSONS 自我进化 · 团队任务板（2.0.0+）|
| 业务编排 | 工作流（7 step mode · Pebble DSL）· 触发器（6 pattern type · 事件治理）· Wiki 加工器（1.3.0+）|
| 能力扩展 | SKILL.md 包 · MCP（stdio / SSE / HTTP · per-agent 绑定）· ACP 桥接（Claude Code / Codex） |
| 数据库 | H2（开发）· MySQL 8.0+（生产）|
@@ -220,6 +223,19 @@ mateclaw/
## 路线图
+**v2.0.0（2026-07-26 发布）** — 从"一个能干活的人"到"一支能协作的队伍"：**Agent 团队**成为常设编制，围着一块共享任务板干活：
+
+- **Agent 团队与共享任务板** — 团队 / 角色（lead · member · reviewer）、八状态看板、`blockedBy` 依赖编排、成员级并行派发、前置结果自动传递、结果通报唤醒 Lead；Teams 页事件驱动实时看板 + 活动横幅 + 任务时间线 + 交付物下载 + 手动投任务
+- **为长任务加固的执行链** — 执行租约 + 运行期心跳防双重执行、取消即真实中断、`in_review` 审批卡点、失败/过期可重试
+- **Plan-Execute 计划整体移交任务板** — 步骤变任务、依赖变并行、停靠恢复门确定性汇总
+- **工作空间隔离全面收口** — 渠道会话 id 编入渠道标识、同名技能跨工作空间共存且运行时按会话工作空间解析
+- **渠道体验** — 全渠道魔法命令（`/new` `/clear` `/status` `/stop` `/model` `/help`）、企业微信事件驱动进度气泡（实时工具轨迹 + 分阶段滚动叙述）
+- **会话回退 / 重新生成服务端语义** · **自动批准未命中可解释**（原因码落审计行 + 一键补策略） · **LLM 错误恢复策略化**（过载/限流分治 · `Retry-After` 回馈退避 · provider TTL 回收）
+
+外加：聊天附件在线预览（pdf / docx / xlsx / html / 文本）、SKILL.md 单一事实源 + 捆绑文件控制台管理、Mem0 可选插件记忆 provider、知识图谱关系模式白名单。
+
+完整故事见 [v2.0.0 release notes](https://claw.mate.vip/docs/zh/releases/2.0.0)。
+
**v1.8.0（2026-07-12 发布）** — 员工*转向对外、干完一整件活*:**内容工作室**——第一个完全用 MateClaw 自身原子能力端到端搭起来的招牌场景:
- **内容工作室——一句话到可发布成品** — 预置「内容工作室」员工跑通 选题 → 搜集 → 成文 → 配图 → 去 AI 化 → 排版 → 交付。**微信公众号(公众号)** 图文文章(内联样式 HTML → 草稿箱)与 **小红书** 以图为主图文笔记(≥3 张竖版 3:4 卡片 + 在线预览)首批一等公民
diff --git a/assets/architecture-biz-en.svg b/assets/architecture-biz-en.svg
index 424421a5..4e511380 100644
--- a/assets/architecture-biz-en.svg
+++ b/assets/architecture-biz-en.svg
@@ -98,10 +98,10 @@
-
-
- Orchestration · Workflow + Trigger
- Events → multi-employee → approval / dispatch / memory
+
+
+ Orchestration · Team Board (2.0.0+) + Workflow + Trigger
+ Lead decomposes → members run in parallel → approve / deliver
diff --git a/assets/architecture-biz-zh.svg b/assets/architecture-biz-zh.svg
index 25133463..5750334f 100644
--- a/assets/architecture-biz-zh.svg
+++ b/assets/architecture-biz-zh.svg
@@ -105,10 +105,10 @@
-
-
- 业务编排 · 工作流 + 触发器
- 事件触发 → 多员工协作 → 审批 / 分发 / 写记忆
+
+
+ 业务编排 · 团队任务板（2.0.0+）+ 工作流 + 触发器
+ Lead 拆解派发 → 成员并行执行 → 审批 / 交付物 / 分发 / 写记忆
diff --git a/assets/architecture-tech-en.svg b/assets/architecture-tech-en.svg
index 1c5afd41..b7e79b4e 100644
--- a/assets/architecture-tech-en.svg
+++ b/assets/architecture-tech-en.svg
@@ -80,9 +80,9 @@
- Workflow + Trigger
- 7 step modes · 6 patterns
- Business orchestration (1.3.0+)
+ Team · Workflow · Trigger
+ Task-board dispatch (2.0.0+)
+ 7 step modes · 6 patterns
diff --git a/assets/architecture-tech-zh.svg b/assets/architecture-tech-zh.svg
index 6fbe8be7..f1f28bfb 100644
--- a/assets/architecture-tech-zh.svg
+++ b/assets/architecture-tech-zh.svg
@@ -83,9 +83,9 @@
- 工作流 + 触发器
- 7 step mode · 6 pattern
- 业务流程编排（1.3.0+）
+ 团队 · 工作流 · 触发器
+ 任务板派发 + 并行（2.0.0+）
+ 7 step mode · 6 pattern
diff --git a/mateclaw-server/src/main/resources/docs/en/channels.md b/mateclaw-server/src/main/resources/docs/en/channels.md
index 45287417..9a47b115 100644
--- a/mateclaw-server/src/main/resources/docs/en/channels.md
+++ b/mateclaw-server/src/main/resources/docs/en/channels.md
@@ -650,7 +650,34 @@ IM channels (WeCom, WeChat, DingTalk) support voice input. Transcription via Das
## Per-conversation model selection (all IM channels)
-As of 1.4.0, IM channel conversations **remember a per-conversation model**, just like web. Each IM conversation seeds a conversation-level model when it's created, and later replies respect that choice rather than always falling back to the agent's default model. See [Chat & Messaging](./chat) for the web-side switching detail.
+As of 1.4.0, IM channel conversations **remember a per-conversation model**, just like web. Each IM conversation seeds a conversation-level model when it's created, and later replies respect that choice rather than always falling back to the agent's default model. See [Chat & Messaging](./chat) for the web-side switching detail. As of 2.0.0 you can also switch right inside the IM with the `/model` magic command (next section).
+
+---
+
+## Channel magic commands (2.0.0+)
+
+In any IM channel, a message that is entirely a `/`-prefixed command is intercepted by a unified dispatcher **before it reaches the LLM** — commands register once and work on every channel, burn no tokens, and respond instantly:
+
+| Command | What it does |
+|------|--------|
+| `/new` | Start a fresh conversation (current context is archived) |
+| `/clear` | Clear the current conversation's context (the conversation itself survives; the 1.8-era clear command folds into this framework) |
+| `/status` | Show the conversation's state — bound employee, model, whether a task is running |
+| `/stop` | Stop the running task — intercepted at the enqueue gate, so it preempts a long task mid-flight |
+| `/model` | List available models / switch **this conversation's** model by name; the switch affects only the current conversation |
+| `/help` | List all commands with descriptions |
+
+Every command carries Chinese and English aliases, is case-insensitive, and matches the whole message exactly — a normal message that merely contains `/stop` never misfires. Command confirmations go through the channel's normal render-and-send path, so an already-posted "thinking…" placeholder bubble is properly consumed instead of spinning forever.
+
+---
+
+## Per-stage progress narration on sync IM channels (2.0.0+)
+
+The worst part of long tasks in IM is the "message dropped into a void" feeling. As of 2.0.0, IM channels on the synchronous path (WeCom, WeChat, …) no longer reply with only the final answer:
+
+- each **stage narration** of the agent's run (what it's doing, which tool it called) arrives as a standalone message — you see the task's footsteps on your phone;
+- WeCom goes further with an **event-driven progress bubble** that updates in place — thinking state, live tool trace and elapsed time roll in real time, and the bubble morphs into the final answer when it arrives (details and tuning in [WeCom Deep Tuning](./wecom-tuning));
+- the web SSE and sync IM paths share one **per-turn stream accumulator**, so both sides see identical execution metadata (tool calls, token usage).
---
@@ -659,6 +686,7 @@ As of 1.4.0, IM channel conversations **remember a per-conversation model**, jus
- **Webhook mode needs HTTPS.** Production deployments should front MateClaw with Nginx + SSL.
- **Long-connection modes need no public IP.** Telegram Long-Polling, DingTalk Stream, Feishu WebSocket, Discord Gateway, Slack Socket mode, WeCom Long connection — all run behind NAT.
- **One channel, one agent.** Different channels can point at different agents.
+- **Conversation ids are channel-scoped (2.0.0).** Conversation id generation now encodes the channel identity — two same-type channels created in different workspaces keep separate conversations even for the same external user, so two workspaces' chats can never bleed into one conversation row.
- **Credentials are encrypted at rest** in `mate_channel`.
- **China networks** often need `http_proxy` configured for Telegram and Discord.
diff --git a/mateclaw-server/src/main/resources/docs/en/chat.md b/mateclaw-server/src/main/resources/docs/en/chat.md
index 601b0a2d..5ed1c1b8 100644
--- a/mateclaw-server/src/main/resources/docs/en/chat.md
+++ b/mateclaw-server/src/main/resources/docs/en/chat.md
@@ -105,6 +105,15 @@ Images handed to a vision-capable model get attached for visual understanding. P
Files a worker generates via tools (documents / images / audio…) are now **persisted to disk** under `data/generated-files/`, with a 7-day retention window + a 6-hour cleanup sweep and an in-memory LRU on top — download links keep working after a restart and are no longer bounded by the old 10-minute in-memory window. The frontend intercepts `/api/v1/files/generated/{id}` downloads via a global click delegator: success goes through an authenticated fetch → blob download; failure (404/410/expired) just shows a toast, **so a dead link no longer wedges the whole page**.
:::
+### In-browser preview: Office / PDF / HTML / text without downloading (2.0.0+)
+
+Images, audio/video and 3D models always previewed inline — but a Word report the agent generated was just a download button: to glance at it you had to download, find the file, open a local app. Now **document attachments open right in the chat**:
+
+- **Click to preview**: pdf / docx / xlsx / html / markdown / txt / code files open in a glass-styled preview layer from the attachment card — uploaded and AI-generated alike.
+- **Pure client-side rendering**: PDF, Word and Excel parse and render in the browser — nothing leaves your machine, no external preview service, the single-JAR and desktop packaging story is unchanged.
+- **Server fallback for the stubborn formats**: pptx and legacy binary Office (doc / xls / ppt) are converted to PDF server-side before preview; if the converter (LibreOffice) isn't present, they degrade gracefully to download — no error, no hang.
+- **Safe HTML preview**: rendered in a sandboxed iframe — interactive pages and charts fully work (scripts run), but the iframe sits in an opaque origin and cannot read the app's login state or local storage.
+
### Primary model can't see images? "Multimodal sidecar" routing
::: tip Added in 1.3.0
@@ -190,6 +199,15 @@ A conversation is a sequence of messages scoped to a single agent and a single u
The segment representation is what powers the progressive display. It also makes the database the source of truth — the UI can reconstruct any past response exactly as it looked while streaming.
+### Rewind and regenerate (2.0.0+)
+
+Two high-frequency actions gained **server-side semantics** in 2.0.0 — no more frontend sleight of hand:
+
+- **Rewind to here**: truncate the conversation back to a message — everything after it is genuinely deleted in the database and the conversation's aggregates (message count, last-message summary) are recomputed. Refresh the page or open from another client and you see the rewound state; "deleted" answers don't resurrect.
+- **Regenerate**: delete the trailing assistant answer and **reuse the original user message** for the re-run — no duplicate user row is inserted. Previously every regenerate added a duplicate question to the database while the old answer haunted the history; now the history stays clean and consistent across refreshes.
+
+The same semantics cover the admin console, the WebChat widget, and the API — all three entrances behave identically. A conversation with an in-flight stream refuses to rewind first, so an actively-writing turn is never truncated.
+
### Per-conversation model selection
::: tip Added in 1.4.0
diff --git a/mateclaw-server/src/main/resources/docs/en/index.md b/mateclaw-server/src/main/resources/docs/en/index.md
index 37ea8581..8e82d200 100644
--- a/mateclaw-server/src/main/resources/docs/en/index.md
+++ b/mateclaw-server/src/main/resources/docs/en/index.md
@@ -23,6 +23,9 @@ features:
- icon: 🧑💼
title: Digital employees, not chatbots
details: You hire coworkers, not a chat box. Each one has a role, a goal, a backstory, a pixel-art avatar, and a color of their own — five career templates ship ready to use. ReAct + Plan-and-Execute, parallel delegation between employees.
+ - icon: 🤝
+ title: Teams, not lone wolves
+ details: Build a team — the lead breaks a goal into tasks on a shared board, members execute in parallel, dependencies orchestrate themselves, prerequisite results hand off automatically, and settled work announces back for synthesis. Leases, cancel-interrupt, approval gates, deliverables and timelines — as of 2.0.0, a crew works around one board.
- icon: 🧩
title: Skills are the skeleton, not a plugin
details: One SKILL.md plus one LESSONS.md that grows with use. Eight starter templates, a five-step creation wizard, pre-flight checks before install. MCP and ACP bridges — even Claude Code and Codex show up as employees.
diff --git a/mateclaw-server/src/main/resources/docs/en/models.md b/mateclaw-server/src/main/resources/docs/en/models.md
index ef0d06a8..6aac7305 100644
--- a/mateclaw-server/src/main/resources/docs/en/models.md
+++ b/mateclaw-server/src/main/resources/docs/en/models.md
@@ -405,6 +405,15 @@ Every provider you add joins an `AvailableProviderPool` that's probed at startup
- **Egress sanitizer** — provider-specific options (e.g., `reasoning_effort` for OpenAI reasoning models) are stripped at egress when failing over to a provider that doesn't support them, so leaked options can't 400 the fallback
- **UI distinguishes 401 from session expiry** — provider auth errors and user session expiry now show different messages with different remediation
+### Policy-driven error recovery and rate-limit-aware backoff (2.0.0+)
+
+Failover decides *who to switch to*; 2.0.0 also makes *how each error recovers* a matter of **classification-as-policy** — every error type carries its recovery attributes (retryable, compress context, rotate, fall back), and the retry loop consumes the policy instead of scattering if-chains. The key semantics:
+
+- **"Server overloaded" and "my key is rate-limited" are treated differently.** A new OVERLOADED class: 503/529-style **server overload** means everyone is queuing — switching providers just burns the whole chain for nothing (and single-key users have nowhere to switch) — so the right move is **back off on the same provider**; a 429 on **your own key** is what deserves a fast rotation. These used to be conflated with opposite policies.
+- **When the provider says when it recovers, we believe it.** `Retry-After` / ratelimit-reset response headers used to go only to logs; they now **feed directly into backoff duration and health cooldown** — no more blind backoff against a known rate-limit window.
+- **Eviction is a TTL cooldown, not a death sentence.** Providers hard-evicted for auth failures or billing now get TTL-based readmission (swap in a new key or top up the account and the system heals itself, no restart required); a provider-stated recovery time overrides the default.
+- **Jittered backoff prevents retry storms.** Concurrent conversations hitting the same rate-limited provider back off with decorrelated jitter — no more lockstep mass retries that keep re-triggering the limit.
+
### Preferred provider drives the primary model (1.5.0)
Before 1.5.0, "per-agent priority" only affected the **failover order** — the primary model was still the global default. 1.5.0 makes that preference **actually decide primary-model selection**. The full precedence is:
diff --git a/mateclaw-server/src/main/resources/docs/en/releases.md b/mateclaw-server/src/main/resources/docs/en/releases.md
index fd1fd233..4184b841 100644
--- a/mateclaw-server/src/main/resources/docs/en/releases.md
+++ b/mateclaw-server/src/main/resources/docs/en/releases.md
@@ -10,6 +10,7 @@ For historical diffs, check the corresponding git tag. For the "why" behind a fe
| Version | Date | Highlights |
|---------|------|------------|
+| [v2.0.0](./releases/2.0.0) | 2026-07-26 | **Agent Teams with a shared task board** — the lead decomposes, members execute in parallel (teams/roles · eight-status kanban · `blockedBy` dependency orchestration · automatic prerequisite hand-off · settled results wake the lead · deliverable registration & download · task timeline + team SSE live board · execution lease heartbeat + cancel-interrupt + `in_review` approval gates) · **Plan-Execute plans hand over to the board** (steps→tasks · dependencies→parallelism · parked-plan resume gate for deterministic synthesis) · Workspace isolation fully sealed (channel-scoped conversation ids · same-named skills coexist per workspace with conversation-scoped runtime resolution) · Channel magic commands (`/new` `/clear` `/status` `/stop` `/model` `/help`) + WeCom event-driven progress bubble (live tool trace · per-stage rolling narration) · Server-side rewind/regenerate semantics · Explainable auto-approval misses (reason codes on audit rows + one-click grant creation + anti-footgun forms) · Policy-driven LLM error recovery (overload vs rate-limit split · `Retry-After`-aware backoff · provider TTL readmission · jitter against retry storms) · In-chat attachment preview (pdf/docx/xlsx/html/text) · Single-source SKILL.md + console bundle-file management · Optional Mem0 plugin memory provider · Knowledge-graph relation schema whitelist |
| [v1.8.0](./releases/1.8.0) | 2026-07-12 | Content Studio — one sentence to a publishable post (seeded "Content Studio" employee runs pick-topic → research → draft → illustrate → de-AI → layout → deliver) · **WeChat Official Account (公众号)** image-text articles (`gzh_article` · inline-style HTML · draft-box publish via `gzh_publish`) + **Xiaohongshu (小红书)** image-first notes (`xhs_note` · ≥3 vertical 3:4 cards · online preview) · Measurable **de-AI-ification** (heuristic AI-trace score → detect/rewrite/re-check loop, max 3 rounds) · Publish chain hardened (body images uploaded into WeChat · AES-GCM secret encryption · WeChat service+token reuse · retry + Chinese error hints · fallback cover) · **Content Calendar** (deliver = compliance-scan + auto-record · topic-fingerprint dedup · read-only page) · Browser agent **accessibility-tree ref interaction** + real-browser privacy guardrails + controlled CDP hatch · Attention anchoring + tool-call loop guard + post-mutation verify reminder · Fast-load (~78% smaller initial bundle) · Context-occupancy panel · Cross-KB wikilinks · MCP progress notifications · Volcano Engine provider · PostgreSQL 16 |
| [v1.7.0](./releases/1.7.0) | 2026-07-04 | Productionization pass — all three approval paths close the loop (workflow approval channel notify + resolve→resume bridge · WebChat/API-Key channel approve+replay · Feishu/WeCom card-click resolves workflow approvals) · Long tasks are visible ("Run Overview" rail + per-turn token breakdown incl. cache hit/miss/write + sub-agent cost rolled up + one-click generated-file download) · Fits the real model window (local-model context-window probing + unified token budget for prefix injection + small-context degradation + tool-schema budget gate) · Opens up (KB / Deep Research open API with API-key+rate-limit+SSE · pluggable search Provider SPI · MCP identity forwarding) · Desktop remote-server connection + `mateclaw-desktop` source open-sourced + LAN deployment mode · One-click operational data export (Dashboard 9-sheet Excel + CLI) · Wiki processing-failure visibility · Per-employee model chain · Debuggable OpenAPI/Swagger |
| [v1.6.0](./releases/1.6.0) | 2026-06-22 | Runs on domestic databases — KingbaseES (人大金仓) + PostgreSQL (one shared PostgreSQL-family migration tree · opt-in Kingbase driver · least-privilege Docker roles) · New senses & hands (image kept in context across turns + `image_analyze` · `execute_code` runs agent-authored code) · You shape the employee (AGENTS.md editor + About You identity + runtime model identity + KB-scope binding + roster tags) · Wiki Sources tab (raw materials + watcher unified, per-KB auto-sync, multi-path/glob, pageType form editor) · Global outbound HTTP/SOCKS proxy · Deterministic Markdown answers · Claude Fable 5 |
diff --git a/mateclaw-server/src/main/resources/docs/en/roadmap.md b/mateclaw-server/src/main/resources/docs/en/roadmap.md
index d07f6d3a..6c5e090c 100644
--- a/mateclaw-server/src/main/resources/docs/en/roadmap.md
+++ b/mateclaw-server/src/main/resources/docs/en/roadmap.md
@@ -130,36 +130,39 @@ The employee turns **outward and finishes a whole job** — from a one-sentence
Full story: [v1.8.0 release notes](./releases/1.8.0.md).
+### v2.0 — It leads a team ✅ Released (2026-07-26)
+
+From "one person who gets things done" to "a team that collaborates" — **Agent Teams** become a standing roster around a shared task board.
+
+- **Team entity and roles**: a team = name + lead + members + reviewers — persisted, reusable; the roster and collaboration playbook inject into member prompts
+- **Shared task board**: eight-status kanban, `blockedBy` dependency orchestration, member-level parallel dispatch, automatic prerequisite hand-off, settled results waking the lead
+- **Lead dispatch**: the lead decomposes, assigns, reviews; a Plan-Execute lead hands its **whole plan over to the board** — steps become tasks, dependencies become parallelism
+- **Execution hardening**: lease heartbeats against double execution, cancel-interrupt, `in_review` human approval gates, retry for failed/stale
+- **Deliverables and full observability**: output files register on tasks, task timelines, a team SSE live board, and jump-in access to any member's word-by-word run
+- Plus: workspace isolation fully sealed, channel magic commands + the WeCom progress bubble, conversation rewind/regenerate, explainable auto-approval, policy-driven LLM error recovery, in-chat attachment preview, single-source SKILL.md, the Mem0 plugin provider
+
+Full story: [v2.0.0 release notes](./releases/2.0.0.md); user guide: [Agent Teams](./teams).
+
---
-## Next: Agent Team & Agent Loop
+## Next: Agent Loop & Team follow-through
> "Great things in business are never done by one person. They're done by a team of people."
-Look back along the line: v1.2 gave employees an identity, v1.3 made flows orchestratable, v1.4 made employees follow goals and spin up delegation trees, v1.5 made autonomy verifiable, v1.7 made long tasks visible.
+Look back along the line: v1.2 gave employees an identity, v1.3 made flows orchestratable, v1.4 made employees follow goals and spin up delegation trees, v1.7 made long tasks visible, and **v2.0 made teams a standing roster**.
-But today's MateClaw still has two "stops":
+One "stop" remains: **employees are reactive.** Goal auto-followup only lives **within a single run**; cron and triggers can wake an employee up, but every wake-up is an isolated response. No employee is truly **on duty** — continuously watching its area of responsibility and deciding for itself when to act.
-**Collaboration is one-shot.** The v1.4 delegation tree is powerful, but it's **task-scoped** — parent delegates child, the task ends, the tree dissolves. The next task starts from zero. Teams have no name, no roster, no accumulated experience — like hiring a fresh batch of temps for every project.
+### Agent Team follow-through — the roster exists; now it grows skills
-**Employees are reactive.** Goal auto-followup only lives **within a single run**; cron and triggers can wake an employee up, but every wake-up is an isolated response. No employee is truly **on duty** — continuously watching its area of responsibility and deciding for itself when to act.
+2.0 delivered the team entity, the task board, lead dispatch and the hardened execution chain (above). Still on the team track:
-v1.9 turns both stops into continuity.
-
-### Agent Team — from "temp hires" to "standing roster"
-
-A team is no longer a tree that sprouts at delegation time and vanishes when the task ends. It becomes a **persistent organizational unit**:
-
-- [ ] **Team entity**: a team = name + leader + member roster + charter — persisted, reusable, exportable and shareable
-- [ ] **Team charter (TEAM.md)**: division of labor, collaboration rules, escalation paths — shapes the team the way AGENTS.md shapes an individual
-- [ ] **Leader dispatch**: tasks come in, the leader decomposes, assigns to the best-fit member, and reviews the result; what it can't handle gets escalated instead of improvised
-- [ ] **Peer review**: critical deliverables can require another member's sign-off before shipping
-- [ ] **Shared team memory**: built on v1.5's TEAM scope — members share team memory and a team file space while personal memories stay isolated
-- [ ] **Team-level goals**: one goal decomposes into member sub-goals; the checklist aggregates across members — hover the leader's avatar to see what the whole team still owes
-- [ ] **Team-to-channel binding**: bind a Feishu / DingTalk group to a team; @ the team in the group, the leader decides who takes it
+- [ ] **Peer review**: critical deliverables can require another member's sign-off before shipping (2.0's `in_review` is human approval; member peer review is the next step)
+- [ ] **Team-level goals**: one goal decomposes into member sub-goals; the checklist aggregates across members — hover the lead's avatar to see what the whole team still owes
+- [ ] **Team-to-channel binding**: bind a Feishu / DingTalk group to a team; @ the team in the group, the lead decides who takes it
- [ ] **Team retrospectives**: task wrap-up auto-generates a retrospective into the team's LESSONS.md — this team does better next time
-- [ ] **Employee Builder upgrade**: v1.4 builds a batch of employees from one sentence; v1.9 makes it emit a **standing team with a charter**
-- [ ] **Run Overview becomes a team view**: each member on-duty / busy / idle at a glance; click through to see what it's working on
+- [ ] **Collaboration DAG / swimlane view**: draw task dependencies and member swimlanes on top of the timeline data
+- [ ] **Employee Builder upgrade**: one sentence emits a **standing team with a roster**
### Agent Loop — from "answers then stops" to "on duty"
@@ -220,8 +223,9 @@ A leader on a loop, members summoned on demand — that's a **self-running digit
| **v1.5** | It's verifiable | Goal checklists + self-maintaining Wiki + owner-aware memory | ✅ Released |
| **v1.6** | It meets you where you are | Domestic databases + persistent vision + code execution + identity shaping | ✅ Released |
| **v1.7** | It's ready for production | Approval paths closed + Run Overview & cost visibility + context/token budgeting + open API/Deep Research + desktop remote/LAN + operational export | ✅ Released |
-| **v1.8** | **It does a whole job** | **Content Studio — one sentence to a publishable 公众号 / 小红书 post + browser ref interaction** | ✅ Released |
-| **v1.9** | **It's on duty** | **Agent Team standing rosters + Agent Loop resident cycles = a department that runs itself** | 📋 Planned |
+| **v1.8** | It does a whole job | Content Studio — one sentence to a publishable 公众号 / 小红书 post + browser ref interaction | ✅ Released |
+| **v2.0** | **It leads a team** | **Agent Teams + a shared task board — the lead decomposes and dispatches, members run in parallel, deliverables and full observability** | ✅ Released |
+| **Next** | **It's on duty** | **Agent Loop resident cycles + team follow-through (peer review / team goals / group binding / retrospectives) = a department that runs itself** | 📋 Planned |
---
diff --git a/mateclaw-server/src/main/resources/docs/en/security.md b/mateclaw-server/src/main/resources/docs/en/security.md
index 2a564c2f..d0836eb0 100644
--- a/mateclaw-server/src/main/resources/docs/en/security.md
+++ b/mateclaw-server/src/main/resources/docs/en/security.md
@@ -308,6 +308,17 @@ curl http://localhost:18088/api/v1/approval/grants \
-H "Authorization: Bearer "
```
+### Auto-approval: hits visible, misses explainable (2.0.0+)
+
+The most maddening pre-2.0 scenario: you configured an auto-approval grant exactly as intuition suggested, and tool calls **still** went to human review — the grants page said "enabled", the audit log said only "needs approval", and nothing anywhere told you why the grant didn't fire. 2.0.0 makes the whole chain transparent:
+
+- **Miss reasons are classified.** The resolver no longer lumps every miss into "no grant": **a grant exists but its severity ceiling is too low** (e.g. a LOW ceiling blocking a HIGH call — the most common trap), no candidate grant at all, workspace mismatch, CRITICAL forced to human review… each gets its own reason code.
+- **The outcome lands on the audit row.** Every guard audit row records the auto-approval outcome and reason — auto-approved calls no longer misleadingly show "needs approval", and calls that went to review show *why* at a glance. Audit rows also carry the real pending-approval id, so you can jump from audit straight to that approval.
+- **One-click grant creation from the audit page.** When you see a "severity ceiling too low" miss, a **create grant** shortcut sits right on the audit row, pre-filled with the tool name, scope, and suggested ceiling — no re-configuring from memory.
+- **Anti-footgun forms.** Scope IDs switch from free text to **scope-typed pickers** (pick an agent for AGENT scope, a conversation for CONVERSATION, a workspace for WORKSPACE), eradicating type-mismatched dead grants at the source; the severity ceiling carries semantic hints ("LOW only auto-approves low-severity calls"); and **cross-workspace dead configurations are rejected at creation** — a grant that could never fire is called out on the spot instead of leaving you guessing in the audit log.
+
+The hard floors are unchanged: CRITICAL always goes to a human, and safety-floor blocks stay non-negotiable.
+
---
## File Guard
diff --git a/mateclaw-server/src/main/resources/docs/en/skills.md b/mateclaw-server/src/main/resources/docs/en/skills.md
index 026387ac..41b3265c 100644
--- a/mateclaw-server/src/main/resources/docs/en/skills.md
+++ b/mateclaw-server/src/main/resources/docs/en/skills.md
@@ -217,8 +217,8 @@ Think of it as "Maven Local Repository, but for skills" — except the local rep
Two sync passes run at boot, so every node has the latest bundle:
-1. `SkillWorkspaceBootstrapRunner` → `BundledSkillSyncer` scans the classpath `skills/` directory and syncs **bundled skills** into the workspace root. **Only syncs when the target directory doesn't exist**, so it never clobbers local modifications.
-2. `SkillFileSyncer` diffs `mate_skill_file` (DB) against the local workspace (FS) by `sha256` and materializes anything missing or stale.
+1. `SkillWorkspaceBootstrapRunner` → `BundledSkillSyncer` scans the classpath `skills/` directory, syncs **bundled skills** into the workspace root, and persists their `scripts/` and `references/` into `mate_skill_file`. Local modifications are normally left alone; but if the on-disk `scripts/` directory has vanished entirely (2.0.0 hardening), it is force-restored from the classpath — a built-in skill's scripts can't stay permanently maimed by one accidental delete.
+2. `SkillFileSyncer` diffs `mate_skill_file` (DB) against the local workspace (FS) by `sha256` and materializes anything missing or stale; for built-in skills with script files in neither DB nor disk, it backfills from the classpath (2.0.0 self-heal path).
**Why this matters for multi-instance deployments**: one node accepts the upload, the DB row + file rows are written, every other node either restarts or hits `POST /api/v1/skills/{id}/sync-files` to receive the full bundle. No NFS, no scp loop, even desktop clients can hand a skill off across machines.
@@ -231,6 +231,7 @@ Third-party packagers package weirdly — some put `setup.sh` at the zip root, s
- **Two-pass extraction** — the entire archive is buffered in memory first (cap-protected, 50 MB by default via `mateclaw.skill.upload.max-total-size-mb`), `SKILL.md` is located and the wrapper-dir prefix computed, then entries are classified. **Zip entry order no longer affects the result.**
- **Root-level extension fallback** — files sitting next to `SKILL.md` that aren't already under a known bucket get classified by extension: `.sh / .py / .js / .rb / ...` → `scripts/`, `.md / .json / .yaml / .csv / ...` → `references/`. Unknown extensions are dropped with a `WARN` line so packaging mistakes surface instead of vanishing.
- **Write-then-prune + empty-bundle guard** — reinstalls **write new files first, then prune anything in the bucket that's not in the new bundle**. If the new bundle has zero entries for a bucket (`scripts/` or `references/`), the disk copies for that bucket are **left alone** — a malformed re-extract can no longer wipe your scripts. Pass `forcePrune=true` if you really want to clear a bucket via an intentionally empty bundle.
+- **No more mojibake in CJK file names** (2.0.0) — zip entry names and file content have their encodings **detected independently**: an archive built by a Windows packer with GBK entry names and UTF-8 content decodes each side correctly, so you no longer get "garbled names but readable content" (or the reverse) after install.
> Real failure this catches: the official tencent-meeting-mcp zip puts `setup.sh` at the package root (not under `scripts/`). The old extractor silently dropped it; the new one auto-classifies it as `scripts/setup.sh` and the skill installs ready to run.
@@ -248,6 +249,27 @@ mateclaw:
---
+## Single-source SKILL.md (2.0.0+)
+
+Before 2.0.0 there was a hidden fork: the runtime read SKILL.md from the workspace directory while the admin console read the database column. An employee editing the file with shell tools in a chat session changed runtime behavior invisibly to the console; conversely, one failed export left agents executing stale content the console claimed was current.
+
+Now the two sides run a **three-way reconcile**, anchored on a sidecar recording the hash at last sync: file-side edits ingest into the DB, DB-side edits materialize to the file, and a two-sided conflict resolves **DB-wins** with the file side kept as a `SKILL.md.bak` backup. A blank file never overwrites non-blank DB content; a blank DB backfills from the file. The reconcile runs on every convention-path resolve, and opening a skill's detail in the console performs a read-time reconcile too — **what you see in the console is what the employee executes.**
+
+(Skills with an explicit `skillDir` stay file-authoritative, mirroring their content into the DB column for display.)
+
+---
+
+## Bundle file management: scripts, references and templates editable from the console (2.0.0+)
+
+The detail drawer used to show and edit only SKILL.md; `scripts/` and `references/` had no console surface at all, and `templates/` wasn't even in the canonical store's bucket set. Now:
+
+- **`/api/v1/skills/{id}/files` admin endpoints**: list / read / upsert / delete a skill's bundle files. Writes land on the canonical `mate_skill_file` row, materialize the workspace cache, and re-resolve the skill immediately — **the employee's next call runs the new script**.
+- **`templates/` becomes a first-class bucket**: DB-persisted like `scripts/` and `references/`, included in sync and backfill, protected by the empty-bundle prune guard.
+- **Path envelope**: only the three convention buckets are allowed and traversal is blocked; built-in skill files stay read-only (restored from the shipped bundle on upgrade); virtual MCP / ACP skills own no files.
+- **Agent-side writes persist too**: when a skill edits its own bundle files via `write_file` in a session, the change mirrors into the canonical store — console and runtime never disagree again.
+
+---
+
## Skill Market (and ClawHub)
The **Skill Market** page (`/skills`) is where you browse, install, edit, and manage skills. Three sources:
@@ -339,9 +361,17 @@ Generate a standup update by analyzing recent git activity.
---
-## Workspace isolation
+## Workspace isolation (fully sealed in 2.0.0)
-Each workspace gets its own copy of skills. When you enable a skill for a workspace, its files are staged under that workspace's directory, the skill's tools are scoped to that workspace, and any file the skill writes stays inside the workspace boundary. As of v1.4 the skill **catalog and runtime are scoped per workspace** too, so each workspace sees and runs only its own skills. See [Workspaces](./workspaces).
+Each workspace gets its own copy of skills. When you enable a skill for a workspace, its files are staged under that workspace's directory, the skill's tools are scoped to that workspace, and any file the skill writes stays inside the workspace boundary.
+
+2.0.0 seals the isolation through **every layer of storage and execution**:
+
+- **Same-named skills coexist across workspaces.** Install dedup, name uniqueness, and reinstall/uninstall lookups all filter by workspace — workspace A's "book-meeting" skill no longer blocks workspace B from installing its own.
+- **Filesystem paths encode the workspace.** The skill directory scheme includes the workspaceId, so two same-named skills own separate directories — no more sharing one directory, overwriting each other, or scripts landing in the neighbor's house.
+- **Runtime resolution is scoped to the conversation's workspace.** `load_skill`, skill file reads, script runs and auto-redirect all resolve only within "this conversation's workspace + builtin + global virtual" — an employee in one workspace cannot read or execute another workspace's same-named skill.
+
+See [Workspaces](./workspaces).
---
diff --git a/mateclaw-server/src/main/resources/docs/en/teams.md b/mateclaw-server/src/main/resources/docs/en/teams.md
new file mode 100644
index 00000000..c079f647
--- /dev/null
+++ b/mateclaw-server/src/main/resources/docs/en/teams.md
@@ -0,0 +1,159 @@
+---
+title: Agent Teams — one lead, a crew of digital employees, one shared task board
+description: MateClaw agent teams let a lead employee break a complex goal into tasks, dispatch them to team members in parallel, with dependencies, approvals, deliverables and full observability on a shared board.
+head:
+ - - meta
+ - name: keywords
+ content: agent teams,task board,kanban,multi-agent collaboration,dispatch,deliverables,MateClaw
+---
+
+# Agent Teams (2.0.0+)
+
+> **Before: one employee with sub-tasks. Now: a team around a shared task board.**
+
+Sub-agent delegation (`delegate_agent`) solves "one person temporarily calls a helper": synchronous, one-to-one, black-box. But real complex delivery looks like a project: **break down tasks, declare dependencies, run in parallel, gate on approvals, archive deliverables, and see who is doing what at any time**.
+
+Agent Teams bring that project machinery into MateClaw: you create a **team**, assign one **lead** employee and several **members**; tell the lead a goal, it breaks the goal into tasks on a **shared task board**; the dispatch engine hands tasks to members and runs them **in parallel**; settled results are announced back to the lead, which reviews, re-dispatches, and drives the whole thing to done. You watch it all from the Teams page — or drop tasks onto the board yourself.
+
+---
+
+## Core concepts
+
+| Concept | Description |
+|------|------|
+| **Team** | A group of employees plus one task board. An employee can belong to multiple teams. |
+| **Role** | `lead` / `member` / `reviewer`. The lead decomposes and summarizes, members execute, reviewers review. |
+| **Task** | One work item on the board: subject, description, assignee, dependencies (`blockedBy`), progress, result, deliverables, comments, timeline. |
+| **Board** | A kanban grouped by status. The state machine is guarded by conditional database updates — under concurrency the first successful writer wins, so a task can never hold two states. |
+
+Eight task statuses:
+
+```
+pending → in_progress → completed / failed / cancelled
+ ↘ in_review (tasks that require human approval)
+blocked (waiting on prerequisites) stale (lease expired, retryable)
+```
+
+`failed` and `stale` tasks can be retried; `completed` / `cancelled` release downstream tasks that depend on them.
+
+---
+
+## What one collaboration run looks like
+
+1. **You give the lead a goal**: "Competitive analysis: research vendors A and B separately, then merge into one report."
+2. **The lead puts tasks on the board**: three tasks via the `team_tasks` tool — "research A" and "research B" run in parallel, "merge report" declares `blockedBy` on both and enters `blocked`.
+3. **The dispatch engine takes over**: a resident sweep (every 30 s, plus an immediate pass after tool/REST actions) assigns pending tasks to their members — each task gets its own child conversation where the member runs the full agent graph. Each member executes one task at a time; the rest queue.
+4. **Prerequisite results are handed off automatically**: once "research A/B" complete, "merge report" is released and its dispatch envelope **automatically carries the results and deliverable links of both prerequisites** — member C doesn't need the lead to retell what member A did.
+5. **Settled results wake the lead**: completions and failures are announced to the lead in debounced batches; the lead wakes up in a real new turn — reviews results, dispatches follow-ups, or declares the job done.
+6. **You see everything**: the Teams board refreshes live (SSE event-driven, no polling), an activity banner streams "#3 dispatched to Content Studio"; open any task for its timeline, progress, comments, deliverables — and **jump into the member's child conversation to watch the run word by word** (a live typewriter while it's running).
+
+---
+
+## The lead's tool: `team_tasks`
+
+The lead (and members) operate the board through the `team_tasks` tool, with role-gated actions:
+
+| Action | Who | What |
+|------|--------|--------|
+| `list` | any member | Render the current board (the lead also gets a live board snapshot injected every turn — see below) |
+| `get` | any member | Task detail |
+| `create` | lead | Create a task: subject, description, assignee, `blockedBy` dependencies, `requireApproval` for a human gate |
+| `complete` | assignee | Submit the result (approval-gated tasks move to `in_review`) |
+| `progress` | assignee | Report percent and current step (also renews the execution lease and broadcasts to the board) |
+| `comment` | any member | Leave a comment |
+| `attach` | assignee | Register a **deliverable** (file name + download URL) on the task |
+| `cancel` | lead | Cancel — this **actually interrupts** a running member session, not just flips a status |
+| `retry` | lead | Retry a `failed` / `stale` task |
+
+**Team context injection**: employees on a team get the team roster and collaboration playbook injected into their system prompt; the lead additionally receives a **live board snapshot every turn** — it never has to call `list` first to know what's on the board, and long conversations can't drift into duplicate task creation.
+
+---
+
+## Execution hardening for long-running tasks
+
+Teams target deep research and long document work — tasks that run for tens of minutes. The execution path is hardened accordingly:
+
+- **Execution lease + runtime heartbeat.** A dispatched task holds a 60-minute lease that is renewed automatically while the member runs; only genuinely lost tasks (process crash, restart) expire to `stale` and can be safely re-dispatched — no more "task re-dispatched while still running, two instances overwriting each other".
+- **Cancel means interrupt.** Member child conversations register with the stream tracker; graph nodes check the stop flag each round, so a cancelled member stops at the next node boundary — no more burning tokens to natural completion after a cancel.
+- **Human approval gates.** Declare `requireApproval` at creation; the submitted task parks at `in_review` until you approve / reject on the Teams page — sensitive output passes a human before it leaves the team.
+- **Manual task creation.** Tasks don't have to come from the lead: create one directly on the Teams page, assigned to any member; the result lands on the board for you (with no lead conversation to wake, announcement gracefully no-ops).
+
+---
+
+## Deliverables and run visibility
+
+The right output shape for a complex task is **files + summary**, not one truncated blob of text:
+
+- Members produce files with the document render tools (docx / pptx / xlsx / pdf) or skills, then `attach` them to the task; the task detail renders a **downloadable attachment list** and the result announcement carries the attachments — links no longer drown in truncated text.
+- Every task detail has a **"view run"** entry: the member child conversation's full transcript — dispatch envelope, round-by-round thinking, tool calls, intermediate output. Opened mid-run it's a live typewriter (reconnects replay the buffer).
+- **Task timeline**: who created / dispatched / reported / attached / approved / cancelled, and when — each event lands in the `mate_team_task_event` audit table and renders as a timeline on the task detail. The collaboration has a historian.
+
+---
+
+## Plan-Execute leads: the plan becomes the board
+
+Leads aren't restricted by agent type. A **ReAct lead** creates tasks one by one via `team_tasks`; a **Plan-Execute lead** goes further — the plan produced by its planning node is **handed over to the board wholesale**:
+
+- plan steps map to board tasks, step dependencies become `blockedBy` — a formerly strictly-serial plan now **parallelizes wherever it can**;
+- after hand-off the plan parks (`delegated`) and the lead's turn ends normally; the dispatch/announce loop takes over;
+- once all tasks settle, the wake-up passes a **parked-plan resume gate** that deterministically routes to the plan summary node, rebuilding context from task results and deliverables — the same "park in DB, resume in a fresh turn" shape the tool-approval flow already uses, with no checkpoint machinery.
+
+In short: **a lead that can plan turns its planning into team orchestration.**
+
+---
+
+## The Teams page
+
+The admin console gains a **Teams** page (`/teams`):
+
+- **Team management**: create teams, add/remove members, assign roles;
+- **Board**: status columns, event-driven live refresh, **paged columns** with **database-side true totals** in the headers — a thousand-task board won't drag the page down;
+- **Activity banner**: streaming dispatch / completion / failure events;
+- **Task detail**: timeline, progress, comments, deliverable downloads, run-transcript entry, approve / reject;
+- **Manual task creation**: drop work onto the board directly.
+
+---
+
+## REST API
+
+The admin API lives under `/api/v1/teams`:
+
+| Endpoint | Description |
+|------|------|
+| `GET / POST /api/v1/teams` | List / create teams |
+| `GET / PUT / DELETE /api/v1/teams/{id}` | Team detail / update / delete |
+| `POST /api/v1/teams/{id}/members` · `DELETE …/members/{agentId}` | Membership |
+| `GET / POST /api/v1/teams/{id}/tasks` | Task list (windowed paging) / create task |
+| `GET /api/v1/teams/{id}/tasks/stats` | Per-status counts (computed database-side) |
+| `GET /api/v1/teams/{id}/tasks/{taskId}` | Task detail |
+| `POST …/tasks/{taskId}/approve · reject · retry · cancel` | Approve / retry / cancel |
+| `POST …/tasks/{taskId}/comments` | Comment |
+| `GET …/tasks/{taskId}/events` | Task timeline |
+| `GET /api/v1/teams/{id}/events` | Team-level SSE event stream (what drives the live board) |
+
+Every validation failure returns a **readable error** — never a bare 500.
+
+Data lives in five tables: `mate_agent_team`, `mate_agent_team_member`, `mate_team_task`, `mate_team_task_comment`, `mate_team_task_event`.
+
+---
+
+## Teams vs. sub-agent delegation (`delegate_agent`)
+
+| | `delegate_agent` | Team task board |
+|---|---|---|
+| Shape | One-off helper call | Standing team + shared board |
+| Parallelism | Single async call | Member-level parallelism + dependency orchestration |
+| Visibility | Black box until done | Timeline + live spectating + deliverables |
+| Interrupt/recover | Tied to parent turn | Leases, cancel-interrupt, retry |
+| Fits | Outsourcing one sub-problem | Multi-role, multi-step project delivery |
+
+They coexist: a team member can still call `delegate_agent` inside its own task.
+
+---
+
+## Read next
+
+- [Agents](./agents) — how the ReAct and Plan-Execute graphs work
+- [Persistent Goals](./goals) — cross-turn follow-through for a single employee
+- [Workflow](./workflow) — deterministic step orchestration (use workflows when the process is fixed, teams when it must be decomposed on the spot)
+- [Security & Approval](./security) — how tool approval relates to team task approval
diff --git a/mateclaw-server/src/main/resources/docs/en/wecom-tuning.md b/mateclaw-server/src/main/resources/docs/en/wecom-tuning.md
index c6aa92f5..53330b1e 100644
--- a/mateclaw-server/src/main/resources/docs/en/wecom-tuning.md
+++ b/mateclaw-server/src/main/resources/docs/en/wecom-tuning.md
@@ -216,6 +216,21 @@ Files live at `data/chat-uploads/{conversationId}/` by default, but when the con
---
+## The progress bubble: long tasks no longer look frozen (2.0.0+)
+
+Before 2.0.0, WeCom replied with one static "🤔 Thinking..." bubble that **never changed** until the final answer — a 30-second-to-3-minute task routinely read as a hang. The placeholder bubble is now **event-driven**:
+
+- **Live tool trace**: the bubble rolls with the agent's run — thinking state, the tool being called, completed calls with elapsed time, appended line by line;
+- **Per-stage rolling**: each new stage (a new reasoning round, a new tool call) refreshes the bubble in place with the current stage narration — you can see exactly how far the task has advanced;
+- **Morphs into the answer**: when the first real content chunk arrives, keepalive is cancelled and the **same stream slot is reused** — the progress bubble becomes the answer in place, leaving no orphan bubble;
+- **Overwrite throttling**: refreshes carry a minimum interval plus a skip-if-previous-flush-pending guard, so WeCom's rate limits are never tripped.
+
+Whether thinking content and the tool trace are shown is still governed by the channel's "message filtering" switches — and as of 2.0.0 those switches genuinely control "should process messages be sent", not merely strip inline tags from the final answer.
+
+Alongside it, **streaming reply management is hardened**: stream slot lifecycles are centrally managed — keepalive, forced finish and context invalidation each in their place — so "the answer landed but the bubble keeps spinning" and "a dangling slot blocks the next message" pathologies are gone. Generated files (images, documents) are also actually delivered through the WeChat channel rather than left as a local-only link.
+
+---
+
## Model behavior: faking tool calls
Observation: **qwen3.6-plus** sometimes "lazes out" in long-context, tool-call-heavy scenarios — it produces a Markdown code block that **mimics** a tool call, but `toolCallCount=0`:
diff --git a/mateclaw-server/src/main/resources/docs/en/wiki.md b/mateclaw-server/src/main/resources/docs/en/wiki.md
index 7374ab75..7e1cd3df 100644
--- a/mateclaw-server/src/main/resources/docs/en/wiki.md
+++ b/mateclaw-server/src/main/resources/docs/en/wiki.md
@@ -663,6 +663,12 @@ Extraction only runs when **entity extraction is enabled** in the KB configurati
In `Wiki → Config → Entity Extraction`: toggling the switch on reveals a tag editor (multi-select, searchable, inline create). The six built-in types are suggested by default; you can type a custom type (e.g. `technology`, `law`) and press Enter to add it. Leaving the list empty falls back to the built-in six. The type list is stored in the KB's `configContent` JSON under the `entityTypes` key.
+### Relation schema: a closed triple whitelist (2.0.0+)
+
+Entity types constrain *what entities* get extracted, but the relation layer used to be open — the model could invent any predicate between any two entities, and fringe entities got persisted as important merely for "participating in some relation", diluting the few definite relations you actually care about.
+
+Each KB can now declare an optional **relation schema**: a closed whitelist of `subjectType → predicate → objectType` triples (e.g. `person → works_at → organization`). With it enabled, extraction **keeps only relations matching the schema and the entities participating in them** — no more free-form invention; the graph contains only the relation shapes you defined. Leave it empty to keep the original open extraction. The config lives in the KB's `configContent`; no migration needed.
+
### Exploring the graph
The Wiki graph view toolbar gains a **Page graph / Entity graph** toggle. In entity graph mode:
diff --git a/mateclaw-server/src/main/resources/docs/en/workspaces.md b/mateclaw-server/src/main/resources/docs/en/workspaces.md
index fce3bf69..4421a7df 100644
--- a/mateclaw-server/src/main/resources/docs/en/workspaces.md
+++ b/mateclaw-server/src/main/resources/docs/en/workspaces.md
@@ -186,6 +186,12 @@ Workspace memory files (PROFILE.md, MEMORY.md, daily notes) live under `workspac
Each channel binds to exactly one agent, so transitively to exactly one workspace. A DingTalk bot configured in workspace A is completely separate from a DingTalk bot configured in workspace B, even if they're configured to connect to the same DingTalk application (you probably don't want that, but it's technically allowed).
+As of 2.0.0, **conversation id generation encodes the channel identity** — two same-type channels created in different workspaces keep separate conversation rows even for the same external user; two workspaces' chats can no longer land in one conversation.
+
+### Skills (2.0.0)
+
+Same-named skills coexist independently across workspaces: install dedup filters by workspace, disk directories encode the workspaceId, and runtime load / file reads / script runs resolve only within the conversation's workspace (+ builtin + global virtual). An employee in one workspace can neither read nor execute another workspace's same-named skill. See [Skills](./skills).
+
---
## What isolation does NOT cover
@@ -197,6 +203,15 @@ Each channel binds to exactly one agent, so transitively to exactly one workspac
---
+## Default storage root and desktop local-tools whitelist (2.0.0+)
+
+Two items landed from issue #512:
+
+- **The default workspace storage root is configurable in the UI.** Each workspace's `base_path` could always be set individually in Security → Workspaces, but the global fallback sandbox root (`mateclaw.workspace.sandbox.root`, default `data/workspace`) used to require an env var or yml edit. It is now a **"default workspace storage path"** setting in the console: files for newly created conversations and workspaces live under it; changing it affects only future creations and **never migrates existing data**.
+- **The desktop local-tools whitelist supports per-entry removal.** The whitelist of directories local tools may access on desktop used to be managed through a native dialog offering only "add" and "disable" — the delete API was dead code. Whitelisted directories are now **listed and individually removable** in the UI.
+
+---
+
## Moving resources between workspaces
Not supported directly. You have two options:
diff --git a/mateclaw-server/src/main/resources/docs/zh/channels.md b/mateclaw-server/src/main/resources/docs/zh/channels.md
index 200a5feb..c3a7dd04 100644
--- a/mateclaw-server/src/main/resources/docs/zh/channels.md
+++ b/mateclaw-server/src/main/resources/docs/zh/channels.md
@@ -650,7 +650,34 @@ IM 渠道（企业微信、微信、钉钉）都支持语音输入。语音识
## 按会话选模型（全 IM 渠道）
-从 1.4.0 起，IM 渠道的会话和 Web 一样会**按会话记住模型**——每个 IM 会话在创建时 seed 一个会话级模型，之后的回复都尊重这个选择，而不是永远用 Agent 的默认模型。Web 侧的切换细节见 [聊天与消息](./chat)。
+从 1.4.0 起，IM 渠道的会话和 Web 一样会**按会话记住模型**——每个 IM 会话在创建时 seed 一个会话级模型，之后的回复都尊重这个选择，而不是永远用 Agent 的默认模型。Web 侧的切换细节见 [聊天与消息](./chat)。2.0.0 起还可以在 IM 里直接用 `/model` 魔法命令切换（见下节）。
+
+---
+
+## 渠道魔法命令（2.0.0+）
+
+在任何 IM 渠道里，以 `/` 开头的整条消息会在进入 LLM **之前**被统一分发器拦截——命令注册一次、全渠道生效，不烧 token、即时响应：
+
+| 命令 | 干什么 |
+|------|--------|
+| `/new` | 开一个新会话（当前上下文归档） |
+| `/clear` | 清空当前会话上下文（保留会话本身；1.8 时代的 clear 命令并入本框架） |
+| `/status` | 查看当前会话状态——绑定的员工、模型、是否有任务在跑 |
+| `/stop` | 停止正在执行的任务——在入队口拦截，可抢在长任务中途生效 |
+| `/model` | 列出可用模型 / 按名切换**本会话**的模型，切换只影响当前会话 |
+| `/help` | 列出全部可用命令与说明 |
+
+每条命令都带中英文别名，大小写不敏感、整串精确匹配——普通消息里包含 `/stop` 字样不会误触发。命令确认消息走渠道的正常渲染发送链路，所以已经贴出的"思考中"占位气泡会被正确消掉，不会留下一个永远转圈的气泡。
+
+---
+
+## 同步 IM 渠道的分阶段进度叙述（2.0.0+）
+
+长任务在 IM 里最大的问题是"发出去像石沉大海"。2.0.0 起，走同步收发的 IM 渠道（企业微信、微信等）不再只回最终答案：
+
+- Agent 执行的**每个阶段叙述**（正在做什么、调用了什么工具）作为独立消息依次送达——你在手机上能看到任务推进的脚印；
+- 企业微信更进一步：**事件驱动的进度气泡**原地滚动更新——思考状态、工具调用轨迹、耗时实时刷新，最终答案到达时气泡原地渐变为答案（细节与调优见 [企业微信深度优化](./wecom-tuning)）；
+- Web SSE 与 IM 同步路径共享同一套**流累积器**，两边看到的执行元数据（工具调用、token 用量）完全一致。
---
@@ -659,6 +686,7 @@ IM 渠道（企业微信、微信、钉钉）都支持语音输入。语音识
- **Webhook 模式需要 HTTPS。** 生产部署应该用 Nginx + SSL 挡在 MateClaw 前面。
- **长连接模式不需要公网 IP。** Telegram Long-Polling、钉钉 Stream、飞书 WebSocket、Discord Gateway、Slack Socket mode、企业微信长连接——全都可以跑在 NAT 后面。
- **一个渠道一个 Agent。** 不同渠道可以指向不同 Agent。
+- **会话 id 按渠道隔离（2.0.0）。** 会话 id 的生成编入了渠道标识——不同工作空间各自新建的同类型渠道，即使面对同一个外部用户，也各有各的会话，不会再把两个工作空间的对话串进同一条会话里。
- **凭证在 `mate_channel` 里加密存储。**
- **国内网络**大概率需要配 `http_proxy` 来访问 Telegram 和 Discord。
diff --git a/mateclaw-server/src/main/resources/docs/zh/chat.md b/mateclaw-server/src/main/resources/docs/zh/chat.md
index 7981b646..bf15f8c2 100644
--- a/mateclaw-server/src/main/resources/docs/zh/chat.md
+++ b/mateclaw-server/src/main/resources/docs/zh/chat.md
@@ -105,6 +105,15 @@ ChatConsole 不只是你自己聊天的地方。它是一个**运营控制台**
员工调工具生成的文件（文档 / 图片 / 音频…）现在**落盘**到 `data/generated-files/`，带 7 天保留窗口 + 6 小时定时清理，内存里再放一层 LRU——下载链接重启后依然有效，不再受原来 10 分钟内存窗口限制。前端用一个全局点击代理拦截 `/api/v1/files/generated/{id}` 下载：成功走鉴权 fetch → blob 下载，失败（404/410/过期）只弹一个 toast，**不再因为一个失效链接把整个页面卡死**。
:::
+### 在线预览：Office / PDF / HTML / 文本不用下载就能看（2.0.0+）
+
+以前图片、音视频、3D 模型都能内联预览，但 Agent 生成的 Word 报告只有一个下载按钮——要看一眼就得下载、找文件、开本地程序。现在**文档类附件在聊天里直接看**：
+
+- **点开即预览**：pdf / docx / xlsx / html / markdown / txt / 代码文件，点击附件卡片在玻璃拟态风格的预览层里打开——上传的和 AI 生成的都一样。
+- **纯前端渲染**：PDF、Word、Excel 都在浏览器里解析渲染，不出网、不依赖任何外部预览服务，单 JAR 与桌面端打包形态不变。
+- **啃不动的格式走服务端兜底**：pptx 与老版二进制 Office（doc / xls / ppt）由服务端转成 PDF 再预览；转换组件（LibreOffice）不在时优雅降级为下载，不报错不卡壳。
+- **HTML 附件安全预览**：在沙箱 iframe 里渲染——交互页面和图表完整可用（脚本可执行），但 iframe 处于隔离源，读不到应用的登录态与本地存储。
+
### 主模型不支持图片？走"多模态旁路"
::: tip 1.3.0 新增
@@ -190,6 +199,15 @@ SSE 流 / 直接响应 ← segment 一段一段送
Segment 的结构是渐进展示的底层。它也让**数据库成为单一事实源**——UI 可以把任何一条历史回复完整地复现成它流式时的样子。
+### 回退与重新生成（2.0.0+）
+
+两个高频动作在 2.0.0 变成了**服务端语义**，不再是前端的障眼法：
+
+- **回退到此处**：把会话截断回某条消息——之后的消息在数据库里真实删除、会话统计（消息数、最后消息摘要）同步重算。刷新页面、换个端打开，看到的都是回退后的状态，被"删掉"的回答不会复活。
+- **重新生成**：删掉末尾那条 assistant 回答、**复用原来的 user 消息**重新执行——不再重复插入 user 行。以前每点一次"重新生成"，数据库里就多一条重复的提问、旧回答还阴魂不散；现在历史干干净净，怎么刷新都一致。
+
+同一套语义覆盖 Admin 控制台、WebChat 挂件和 API——三个入口的行为完全一致。有在途流的会话会先拒绝回退，避免截断正在写入的回合。
+
### 按会话选模型
::: tip 1.4.0 新增
diff --git a/mateclaw-server/src/main/resources/docs/zh/index.md b/mateclaw-server/src/main/resources/docs/zh/index.md
index 7ec5c7ac..2887d5b5 100644
--- a/mateclaw-server/src/main/resources/docs/zh/index.md
+++ b/mateclaw-server/src/main/resources/docs/zh/index.md
@@ -23,6 +23,9 @@ features:
- icon: 🧑💼
title: 数字员工，不是聊天机器人
details: 你雇佣同事，不是开聊天框。每位有角色 / 目标 / 背景故事、像素艺术头像、专属配色——5 个职业模板开箱可用。ReAct + Plan-and-Execute 双模式，员工之间并行委派。
+ - icon: 🤝
+ title: 团队，不是单打独斗
+ details: 建一个团队：Lead 把目标拆成任务落到共享任务板，成员并行执行，依赖自动编排、前置结果自动传递、结果自动通报汇总。执行租约、取消即中断、审批卡点、交付物与任务时间线——2.0.0 起，一支队伍围着一块看板干活。
- icon: 🧩
title: 技能是骨架，不是插件
details: 一份 SKILL.md + 一份 LESSONS.md（用得越多越聪明）。8 个起步模板，向导 5 步出包，安装前自动 Pre-flight 检查。MCP / ACP 双桥接，连 Claude Code、Codex 都能进来当员工。
diff --git a/mateclaw-server/src/main/resources/docs/zh/models.md b/mateclaw-server/src/main/resources/docs/zh/models.md
index c6c4df9f..808c61a7 100644
--- a/mateclaw-server/src/main/resources/docs/zh/models.md
+++ b/mateclaw-server/src/main/resources/docs/zh/models.md
@@ -406,6 +406,15 @@ MateClaw 用一个**活跃模型**作为全局默认。没有指定自己模型
- **出口 sanitizer** —— provider 专属选项（如 OpenAI 推理模型的 `reasoning_effort`）在 failover 到不支持的 provider 时被剥离，泄漏的选项不会让 fallback 报 400
- **UI 区分 401 与会话过期** —— provider 认证错误和用户会话过期现在显示不同消息、不同处置
+### 策略化错误恢复与限流感知退避（2.0.0+）
+
+failover 决定"切给谁"，2.0.0 把"什么错该怎么恢复"也做成了**策略即分类**——每种错误类型自带恢复属性（可否重试、是否压缩上下文、是否轮换、是否降级），重试循环只消费策略，不再散落 if 链。几处关键语义：
+
+- **"服务端过载"与"自己被限流"分开治**。新增 OVERLOADED 分类：503/529 这类**服务端过载**是全网都在排队，切 provider 只会把整条链白白烧一遍（单 key 用户更是无处可切）——正确动作是**同 provider 退避等待**；而 429 打在**自己 key** 上的限流才值得快速切换。以前这两种被混在一起、策略相反。
+- **Provider 说几点恢复，就几点恢复**。响应头里的 `Retry-After` / ratelimit-reset 以前只进日志，现在**直接回馈到退避时长与健康冷却**——不再对着限流窗口盲退避浪费时间。
+- **摘除不是判死，是带 TTL 的冷却**。认证失败、欠费被硬摘除的 provider 现在按 TTL 自动回收重试（例如换绑了新 key、账户充了值，系统自己恢复，不再需要人工重启）；provider 明确给出恢复时刻时以其为准。
+- **抖动退避防重试风暴**。并发会话撞上同一个限流 provider 时，退避加去相关抖动——不会所有会话以同一节奏集体重试、持续触发限流。
+
### 偏好提供商决定主模型（1.5.0）
1.5.0 之前，"每个 agent 自定义优先级"只影响 **failover 顺序**——主模型仍是全局默认。1.5.0 让这个偏好**真的决定主模型选择**。完整优先级链是：
diff --git a/mateclaw-server/src/main/resources/docs/zh/releases.md b/mateclaw-server/src/main/resources/docs/zh/releases.md
index 03886f2b..d769ce70 100644
--- a/mateclaw-server/src/main/resources/docs/zh/releases.md
+++ b/mateclaw-server/src/main/resources/docs/zh/releases.md
@@ -10,6 +10,7 @@
| 版本 | 日期 | 亮点 |
|------|------|------|
+| [v2.0.0](./releases/2.0.0) | 2026-07-26 | **Agent 团队与共享任务板**——Lead 拆任务、成员并行执行（团队/角色 · 八状态看板 · `blockedBy` 依赖编排 · 前置结果自动传递 · 结果通报唤醒 Lead · 交付物登记下载 · 任务时间线 + 团队 SSE 实时看板 · 执行租约心跳 + 取消即中断 + `in_review` 审批卡点） · **Plan-Execute 计划整体移交任务板**（步骤→任务 · 依赖→并行 · 停靠恢复门确定性汇总） · 工作空间隔离全面收口（渠道会话 id 编入渠道 · 同名技能跨工作空间共存且运行时按会话工作空间解析） · 渠道魔法命令（`/new` `/clear` `/status` `/stop` `/model` `/help`）+ 企微事件驱动进度气泡（实时工具轨迹 · 分阶段滚动叙述） · 会话回退/重新生成服务端语义 · 自动批准未命中可解释（原因码落审计行 + 一键补策略 + 表单防呆） · LLM 错误恢复策略化（过载/限流分治 · `Retry-After` 回馈退避 · provider TTL 回收 · 抖动防重试风暴） · 聊天附件在线预览（pdf/docx/xlsx/html/文本） · SKILL.md 单一事实源 + 捆绑文件控制台管理 · Mem0 可选插件记忆 provider · 知识图谱关系模式白名单 |
| [v1.8.0](./releases/1.8.0) | 2026-07-12 | 内容工作室——一句话到可发布成品（预置「内容工作室」员工跑通 选题→搜集→成文→配图→去AI化→排版→交付） · **微信公众号（公众号）** 图文文章（`gzh_article` · 内联样式 HTML · `gzh_publish` 推进草稿箱）+ **小红书** 以图为主图文笔记（`xhs_note` · ≥3 张竖版 3:4 卡片 · 在线预览） · 可度量**去 AI 化**（启发式 AI 痕迹评分 → 检测/改写/复检闭环,硬上限 3 轮） · 发布链加固（正文图上传进微信 · AES-GCM 密钥加密 · 微信服务+token 复用 · 重试 + 中文错误提示 · 兜底封面） · **内容日历**（交付即合规扫描 + 自动落台账 · 选题指纹去重 · 只读页） · 浏览器 Agent **无障碍树 ref 交互** + 真实浏览器隐私护栏 + 受控 CDP 逃生舱 · 注意力锚定 + 工具调用循环护栏 + 改动后校验提醒 · 快加载（初始包体 ↓约 78%） · 上下文占用面板 · 跨知识库 wikilink · MCP 进度通知 · 火山方舟供应商 · PostgreSQL 16 |
| [v1.7.0](./releases/1.7.0) | 2026-07-04 | 生产化加固 —— 审批体系打通三条链路（工作流审批渠道通知 + resolve→resume 桥接 · WebChat/API-Key 渠道审批 resolve+replay · 飞书/企微卡片点击 resolve 工作流审批） · 长任务看得见（「运行总览」侧栏 + 本轮 Token 明细含缓存命中/未命中/写入 + 子 Agent 成本向上滚加 + 生成文件一键下载） · 装得下真实模型窗口（本地模型上下文窗口探测 + prefix 注入统一 Token 预算 + 小上下文降级 + 工具 schema 预算门） · 开放出去（知识库 / Deep Research 开放 API 含 API-Key+限流+SSE · 插件化搜索 Provider SPI · MCP 身份透传） · 桌面端远程 Server 连接 + `mateclaw-desktop` 源码开源 + 局域网部署模式 · 运营数据一键导出（Dashboard 9 表 Excel + CLI 命令行） · Wiki 处理失败可视化 · 按员工模型链 · OpenAPI/Swagger 可调试 |
| [v1.6.0](./releases/1.6.0) | 2026-06-22 | 跑在国产数据库上 —— KingbaseES(人大金仓)+ PostgreSQL（共用一套 PostgreSQL 家族迁移树 · 按需金仓驱动 · Docker 最小权限角色） · 新感官与双手（图片跨轮次留在上下文 + `image_analyze` · `execute_code` 运行员工编写的代码） · 你来塑造员工（AGENTS.md 编辑器 + About You 身份 + 运行时模型身份 + KB 范围绑定 + 花名册标签） · Wiki Sources 标签（素材与监听合并、按 KB 自动同步、多路径/glob、pageType 表单编辑器） · 全局出站 HTTP/SOCKS 代理 · 确定性 Markdown 回答 · Claude Fable 5 |
diff --git a/mateclaw-server/src/main/resources/docs/zh/roadmap.md b/mateclaw-server/src/main/resources/docs/zh/roadmap.md
index ff51f61a..07791a73 100644
--- a/mateclaw-server/src/main/resources/docs/zh/roadmap.md
+++ b/mateclaw-server/src/main/resources/docs/zh/roadmap.md
@@ -130,36 +130,39 @@ MateClaw 就是这个东西。
完整故事：[v1.8.0 Release Notes](./releases/1.8.0.md)。
+### v2.0 —— 它带队干活 ✅ 已发布（2026-07-26）
+
+从"一个能干活的人"到"一支能协作的队伍"——**Agent 团队**成为常设编制，围着一块共享任务板协作。
+
+- **团队实体与角色编制**：团队 = 名字 + Lead + 成员 + reviewer，持久化、可复用；团队名册与协作准则注入成员提示词
+- **共享任务板**：八状态看板、`blockedBy` 依赖编排、成员级并行派发、前置结果自动传递、结果通报唤醒 Lead
+- **队长调度**：Lead 拆任务、指派、验收；Plan-Execute 型 Lead 的计划**整体移交任务板**——步骤变任务、依赖变并行
+- **执行加固**：租约心跳防双重执行、取消即中断、`in_review` 人工审批卡点、失败/过期可重试
+- **交付物与全程可观测**：产出文件登记到任务、任务时间线、团队 SSE 实时看板、跳进成员子会话看逐字执行
+- 外加：工作空间隔离全面收口、渠道魔法命令 + 企微进度气泡、会话回退/重新生成、自动批准可解释性、LLM 错误恢复策略化、附件在线预览、SKILL.md 单一事实源、Mem0 插件 provider
+
+完整故事：[v2.0.0 Release Notes](./releases/2.0.0.md)，使用指南：[团队协作](./teams)。
+
---
-## 下一站：Agent Team 与 Agent Loop
+## 下一站：Agent Loop 与团队进阶
> "伟大的事业不是一个人做成的，是一个团队做成的。"
-回头看这条线：v1.2 员工有了身份，v1.3 流程能编排，v1.4 员工会自主跟目标、能临时拉起委派树，v1.5 自主变得可验证，v1.7 长任务看得见。
+回头看这条线：v1.2 员工有了身份，v1.3 流程能编排，v1.4 员工会自主跟目标、能临时拉起委派树，v1.7 长任务看得见，**v2.0 团队成了常设编制**。
-但今天的 MateClaw 还有两个"停"：
+还剩一个"停"：**员工是被动的。** 目标的自动延续只活在**单次运行内**；cron 和触发器能定时叫醒它，但每次醒来都是一次孤立的响应。没有一个员工真正"在岗"——持续盯着自己的职责范围，自己决定什么时候该干什么。
-**协作是一次性的。** v1.4 的委派树很强，但它是**任务级**的——parent 委派 child，任务结束，树就散了。下一个任务再从零拉起。团队没有名字、没有编制、没有沉淀——像每个项目都重新招一批临时工。
+### Agent Team 进阶 —— 编制有了，接下来长本事
-**员工是被动的。** 目标的自动延续只活在**单次运行内**；cron 和触发器能定时叫醒它，但每次醒来都是一次孤立的响应。没有一个员工真正"在岗"——持续盯着自己的职责范围，自己决定什么时候该干什么。
+2.0 交付了团队实体、任务板、队长调度与执行链（见上），团队方向还想做：
-v1.9 要把这两个"停"变成"续"。
-
-### Agent Team（智能体团队）—— 从"临时拉人"到"常设编制"
-
-一个团队不再是委派时临时长出来、任务结束就消失的树，而是一个**持久化的组织单元**：
-
-- [ ] **团队实体**：一个团队 = 名字 + 队长（Leader）+ 成员编制 + 章程，持久化、可复用、可导出分享
-- [ ] **团队章程（TEAM.md）**：分工、协作规则、升级路径——像 AGENTS.md 塑造个人一样塑造团队
-- [ ] **队长调度**：任务进来队长拆解、指派给最合适的成员、验收结果；干不了的向上汇报而不是硬编
-- [ ] **成员互审（peer review）**：关键产出可以配置"另一个成员复核后才交付"
-- [ ] **团队共享记忆**：基于 v1.5 的 TEAM scope——团队成员共享一份团队记忆和团队文件空间，个人记忆仍然互不串台
+- [ ] **成员互审（peer review）**：关键产出可以配置"另一个成员复核后才交付"（2.0 的 `in_review` 是人工审批；成员互审是下一步）
- [ ] **团队级目标**：一个 goal 拆成成员子目标，清单跨成员汇总——hover 队长头像，看到整个团队还差哪几条
- [ ] **团队绑渠道**：一个飞书群 / 钉钉群绑一个团队，群里 @ 团队，队长决定谁接
- [ ] **团队复盘**：任务收尾自动生成 retrospective，沉淀进团队的 LESSONS.md——这个团队下次会做得更好
-- [ ] **「数字员工构建器」升级**：v1.4 已经能一句话建一批员工，v1.9 让它直接产出一个**带章程的常设团队**
-- [ ] **运行总览升级为团队视图**：每个成员在岗 / 忙碌 / 空闲一眼看清，点进去看它正在干的事
+- [ ] **协作 DAG / 泳道视图**：在时间线数据之上画出任务依赖与成员泳道
+- [ ] **「数字员工构建器」升级**：一句话直接产出一个**带编制的常设团队**
### Agent Loop（智能体循环）—— 从"答完就停"到"长期在岗"
@@ -220,8 +223,9 @@ v1.9 要把这两个"停"变成"续"。
| **v1.5** | 它可验证 | 目标清单 + Wiki 自维护 + 记忆认人 | ✅ 已发布 |
| **v1.6** | 它来到你所在的地方 | 国产数据库 + 视觉留存 + 代码执行 + 身份塑造 | ✅ 已发布 |
| **v1.7** | 它敢放进生产 | 审批三链路闭环 + 运行总览与成本可见 + 上下文/Token 预算 + 开放 API/Deep Research + 桌面远程/局域网 + 运营导出 | ✅ 已发布 |
-| **v1.8** | **它干完一整件活** | **内容工作室 —— 一句话到可发布的公众号 / 小红书成品 + 浏览器 ref 交互** | ✅ 已发布 |
-| **v1.9** | **它长期在岗** | **Agent Team 常设团队 + Agent Loop 常驻循环 = 会自己运转的数字部门** | 📋 规划中 |
+| **v1.8** | 它干完一整件活 | 内容工作室 —— 一句话到可发布的公众号 / 小红书成品 + 浏览器 ref 交互 | ✅ 已发布 |
+| **v2.0** | **它带队干活** | **Agent 团队 + 共享任务板 —— Lead 拆解派发、成员并行执行、交付物与全程可观测** | ✅ 已发布 |
+| **下一站** | **它长期在岗** | **Agent Loop 常驻循环 + 团队进阶（互审 / 团队目标 / 群绑定 / 复盘）= 会自己运转的数字部门** | 📋 规划中 |
---
diff --git a/mateclaw-server/src/main/resources/docs/zh/security.md b/mateclaw-server/src/main/resources/docs/zh/security.md
index 964b3849..38b8e8d1 100644
--- a/mateclaw-server/src/main/resources/docs/zh/security.md
+++ b/mateclaw-server/src/main/resources/docs/zh/security.md
@@ -308,6 +308,17 @@ curl http://localhost:18088/api/v1/approval/grants \
-H "Authorization: Bearer "
```
+### 自动批准：命中要可见，未命中要可解释（2.0.0+）
+
+以前最气人的场景：你按直觉配好了自动批准策略，工具调用**还是**进了人审——策略页显示"已启用"，审计日志只写"需审批"，全程没有一处告诉你为什么没放行。2.0.0 把这条链路做成透明的：
+
+- **未命中原因细分**。自动批准解析器不再把所有未命中笼统记成"无策略"：**有策略但严重度上限不够**（比如上限 LOW 挡住了 HIGH 的调用——最常见的踩坑）、根本没有候选策略、工作区不匹配、CRITICAL 强制人审……每种原因都有独立的原因码。
+- **结果落在审计行上**。守卫审计日志的每一行都记录自动批准的最终结果与原因——自动放行的调用不再误导性地显示"需审批"，进人审的调用能一眼看到"为什么"。审计行还挂上了真实的待审批 ID，能从审计直接跳到那次审批。
+- **审计页一键补策略**。看到"严重度上限不够"这类未命中，审计行旁边就是**创建授权**快捷入口，带着工具名、范围、建议的严重度上限直接进表单——不用凭记忆重新配。
+- **表单防呆**。范围 ID 从自由文本换成**按范围类型的选择器**（AGENT 选智能体、CONVERSATION 选会话、WORKSPACE 选工作区），配错类型的死策略从源头绝迹；严重度上限带语义提示（"LOW 只放行低危调用"）；**跨工作区的死配置在创建时直接拒绝**——配了永远不可能生效的策略，系统当场告诉你，而不是让你在审计日志里猜。
+
+CRITICAL 永远人审、safety floor 硬拦截的底线语义不变。
+
---
## File Guard
diff --git a/mateclaw-server/src/main/resources/docs/zh/skills.md b/mateclaw-server/src/main/resources/docs/zh/skills.md
index 0a733274..c81e1042 100644
--- a/mateclaw-server/src/main/resources/docs/zh/skills.md
+++ b/mateclaw-server/src/main/resources/docs/zh/skills.md
@@ -217,8 +217,8 @@ scripts:
启动时跑两遍同步，保证每个节点拿到的都是最新的：
-1. `SkillWorkspaceBootstrapRunner` → `BundledSkillSyncer` 扫描 classpath 的 `skills/` 目录，把**捆绑技能**同步到工作空间根。**只在目标目录不存在时同步**，不会覆盖本地修改。
-2. `SkillFileSyncer` 比对 `mate_skill_file`（DB）与本地工作空间（FS），按 `sha256` 增量物化缺失或过期的文件。
+1. `SkillWorkspaceBootstrapRunner` → `BundledSkillSyncer` 扫描 classpath 的 `skills/` 目录，把**捆绑技能**同步到工作空间根，并把 `scripts/` 与 `references/` 一并持久化进 `mate_skill_file`。常规情况下不覆盖本地修改；但如果磁盘上的 `scripts/` 目录整个丢了（2.0.0 加固），会强制从 classpath 恢复——内置技能的脚本不会因为一次误删就永久残缺。
+2. `SkillFileSyncer` 比对 `mate_skill_file`（DB）与本地工作空间（FS），按 `sha256` 增量物化缺失或过期的文件；内置技能在 DB 与磁盘都没有脚本文件时，还会从 classpath 回填（2.0.0 自愈路径）。
**多实例部署的意义**：一个节点上传 zip，DB row 与 file rows 写入；其他节点重启或调一次 `POST /api/v1/skills/{id}/sync-files` 就能拿到完整 bundle，不用 NFS、不用脚本拷贝、桌面端跨机也能接力。
@@ -231,6 +231,7 @@ scripts:
- **两遍扫描**——先把所有条目缓存（受总大小上限保护，默认 50 MB，可用 `mateclaw.skill.upload.max-total-size-mb` 调整），定位 `SKILL.md` 算出 wrapper 前缀，再分类。**条目顺序不再影响结果**。
- **根目录扩展名兜底**——SKILL.md 同级的非约定文件按扩展名归类：`.sh / .py / .js / .rb / ...` → `scripts/`，`.md / .json / .yaml / .csv / ...` → `references/`，未识别扩展名落 `WARN` 日志。
- **写后裁剪 + 空 bundle 守卫**——重装时**先写新文件再裁剪不在新 bundle 里的旧文件**。如果新 bundle 某个桶（`scripts/` 或 `references/`）一个条目都没有，**保留磁盘上的旧文件**——一个解析失败的损坏 zip 不会再把你的 skill 擦干净。要强制清空就传 `forcePrune=true`。
+- **中文文件名不再乱码**（2.0.0）——zip 条目名与文件内容**分别独立探测编码**：Windows 压缩工具打出的 GBK 文件名和 UTF-8 内容各按各的编码解，安装后不再出现"文件名乱码但内容正常"或反过来的组合。
> 这道门管得住的实际场景：上次实测中腾讯会议 zip 的 `setup.sh` 在根（不在 `scripts/` 子目录），旧 extractor 静默丢弃；新 extractor 自动归到 `scripts/setup.sh`，安装完直接可跑。
@@ -248,6 +249,27 @@ mateclaw:
---
+## SKILL.md 单一事实源（2.0.0+）
+
+2.0.0 之前有一个隐蔽的分叉：运行时从工作空间目录读 SKILL.md，控制台读数据库列——员工在会话里用 shell 工具改了文件，运行行为变了，控制台却看不见；反过来一次失败的导出会让员工执行着过期内容，控制台还声称一切正常。
+
+现在两边**三向调和**：以一个记录上次同步哈希的 sidecar 为锚——文件侧改动自动入库，DB 侧改动自动物化到文件，两边都改过的冲突按 **DB 赢**并把文件侧留成 `SKILL.md.bak` 备份。空文件永远不会覆盖非空的 DB 内容；空 DB 会从文件回填。调和在每次按约定路径解析时执行，控制台打开技能详情也会做一次读取时调和——**你在控制台看到的，就是员工正在执行的。**
+
+（显式指定 `skillDir` 的技能保持文件权威，内容镜像进 DB 列仅供展示。）
+
+---
+
+## 捆绑文件管理：脚本、参考资料、模板都能在控制台改（2.0.0+）
+
+以前技能详情抽屉只能看和改 SKILL.md；`scripts/` 和 `references/` 在控制台完全没有入口，`templates/` 甚至不在权威存储的桶清单里。现在：
+
+- **`/api/v1/skills/{id}/files` 管理端点**：列出 / 读取 / 写入 / 删除技能的捆绑文件。写入落权威的 `mate_skill_file` 行、同步物化工作空间缓存、并立即让技能重新解析——**员工下一次调用就用上新脚本**。
+- **`templates/` 成为一等桶**：与 `scripts/`、`references/` 一样入库持久化、参与同步与回填、受空 bundle 裁剪守卫保护。
+- **路径信封防护**：只允许三个约定桶，阻断路径穿越；内置技能的文件保持只读（升级时从出厂 bundle 恢复）；MCP / ACP 虚拟技能没有文件。
+- **员工侧写入同样入库**：会话里技能用 `write_file` 改自己的捆绑文件时，改动同步镜像进权威存储——控制台与运行时不再各说各话。
+
+---
+
## 技能市场（以及 ClawHub）
**技能市场** 页面（`/skills`）是你浏览、安装、编辑、管理技能的地方。三个来源：
@@ -338,9 +360,17 @@ parameters:
---
-## 工作空间隔离
+## 工作空间隔离（2.0.0 全面收口）
-每个工作空间都有自己的一份技能副本。给某个工作空间启用一个技能时，它的文件被 stage 到那个工作空间的目录下、技能的工具被 scope 到这个工作空间、技能写任何文件都在工作空间边界内。v1.4 起技能**目录与运行时也按工作空间隔离**，每个工作空间只看到、只运行属于自己的技能。见 [工作空间](./workspaces)。
+每个工作空间都有自己的一份技能副本。给某个工作空间启用一个技能时，它的文件被 stage 到那个工作空间的目录下、技能的工具被 scope 到这个工作空间、技能写任何文件都在工作空间边界内。
+
+2.0.0 把隔离从"目录展示"收口到**存储与执行的每一层**：
+
+- **同名技能可在不同工作空间共存**。安装查重、名称唯一性、重装/卸载查找全部按工作空间过滤——A 工作空间装了「预约会议」，不再挡住 B 工作空间装自己的同名技能。
+- **文件系统路径编入工作空间**。技能目录 scheme 带上 workspaceId，两个工作空间的同名技能各有各的磁盘目录——不会共用一个目录互相覆盖、脚本落到对方家里。
+- **运行时按会话工作空间解析**。`load_skill` / 读技能文件 / 跑技能脚本 / 自动重定向，全部只在「本会话工作空间 + builtin + 全局 virtual」范围内解析——一个工作空间的员工不可能读到或执行另一个工作空间的同名技能。
+
+见 [工作空间](./workspaces)。
---
diff --git a/mateclaw-server/src/main/resources/docs/zh/teams.md b/mateclaw-server/src/main/resources/docs/zh/teams.md
new file mode 100644
index 00000000..502febd8
--- /dev/null
+++ b/mateclaw-server/src/main/resources/docs/zh/teams.md
@@ -0,0 +1,159 @@
+---
+title: 团队协作 — 一个 Lead 带一群数字员工，在共享任务板上并行干活
+description: MateClaw 的 Agent 团队让一个 Lead 员工把复杂目标拆成任务、派给团队成员并行执行，任务板负责依赖、审批、交付物与全程可观测。
+head:
+ - - meta
+ - name: keywords
+ content: Agent团队,任务板,看板,多Agent协作,派发,交付物,团队协作,MateClaw
+---
+
+# 团队协作（2.0.0+）
+
+> **以前是"一个员工带子任务"。现在是"一个团队围着一块任务板"。**
+
+子员工委派（`delegate_agent`）解决的是"一个人临时叫帮手"：同步等结果、一对一、过程黑盒。但真实的复杂交付不长这样——它长得像一个项目：**拆任务、标依赖、并行推进、卡点审批、交付物归档、随时能看谁在干什么**。
+
+团队协作把这套项目机制搬进 MateClaw：你建一个**团队**，指定一个 **Lead** 员工、若干**成员**员工；对 Lead 说一句目标，它把目标拆成任务落到**共享任务板**上；派发引擎把任务自动分给成员**并行执行**；成员完成后结果自动通报回 Lead，由它汇总、补派、直到整件事干完。你全程在 Teams 页旁观——或者直接往板上投任务。
+
+---
+
+## 核心概念
+
+| 概念 | 说明 |
+|------|------|
+| **团队（Team）** | 一组员工 + 一块任务板。一个员工可以加入多个团队。 |
+| **角色（Role）** | `lead` / `member` / `reviewer` 三种。Lead 负责拆解与汇总，成员负责执行，reviewer 参与审阅。 |
+| **任务（Task）** | 板上的一条工作项：标题、描述、指派人、依赖（`blockedBy`）、进度、结果、交付物、评论、时间线。 |
+| **任务板（Board）** | 按状态分列的看板。状态机由数据库条件更新守卫——并发场景下谁先改成功谁算数，不会出现双重状态。 |
+
+任务状态一共八种：
+
+```
+pending → in_progress → completed / failed / cancelled
+ ↘ in_review（要求人工审批的任务）
+blocked（等前置任务） stale（租约过期，可重试）
+```
+
+`failed` 与 `stale` 的任务可以重试；`completed` / `cancelled` 会放行依赖它的下游任务。
+
+---
+
+## 一次典型协作长什么样
+
+1. **你对 Lead 说目标**：“做一份竞品分析：先各自调研 A、B 两家，再汇总成一份报告。”
+2. **Lead 拆任务上板**：调用 `team_tasks` 工具建三条任务——“调研 A”“调研 B”并行，“汇总报告”声明 `blockedBy` 前两条，自动进入 `blocked`。
+3. **派发引擎接手**：常驻扫描（30 秒一轮，工具/REST 动作后立即加扫）把 pending 任务派给指派成员——每个任务开一个独立子会话，成员在里面跑完整的 Agent 图。每个成员同时只吃一个任务，其余排队。
+4. **前置结果自动传递**：“调研 A/B”完成后，“汇总报告”被放行，派发信封里**自动带上两条前置任务的结果与交付物链接**——成员 C 不需要 Lead 人肉转述成员 A 干了什么。
+5. **结果通报唤醒 Lead**：任务落定（完成/失败）后合批通报给 Lead，Lead 被唤醒发起真实新一轮——检查结果、补派任务或宣布收工。
+6. **你全程可见**：Teams 页的看板实时刷新（SSE 事件驱动，不靠轮询），活动横幅滚动播报“#3 已派发给内容工作室”；点开任务能看时间线、进度、评论、交付物，还能**跳进成员子会话看它逐字执行的全过程**——运行中打开就是打字机直播。
+
+---
+
+## Lead 手里的工具：`team_tasks`
+
+Lead（和成员）通过 `team_tasks` 工具操作任务板，动作按角色门禁：
+
+| 动作 | 谁能用 | 干什么 |
+|------|--------|--------|
+| `list` | 所有成员 | 渲染当前任务板（Lead 每轮还会自动收到实时看板快照，见下） |
+| `get` | 所有成员 | 查看单个任务详情 |
+| `create` | Lead | 建任务：标题、描述、指派成员、`blockedBy` 依赖、`requireApproval` 是否需人工审批 |
+| `complete` | 执行成员 | 提交结果完成任务（要求审批的任务转入 `in_review` 等人批） |
+| `progress` | 执行成员 | 上报进度百分比与当前步骤（同时给执行租约续期并广播到看板） |
+| `comment` | 所有成员 | 在任务下留言 |
+| `attach` | 执行成员 | 给任务挂**交付物**（文件名 + 下载链接） |
+| `cancel` | Lead | 取消任务——**会真的中断**正在执行的成员会话，不是只改个状态 |
+| `retry` | Lead | 重试 `failed` / `stale` 的任务 |
+
+**团队上下文注入**：加入团队的员工，system prompt 会注入团队名册与协作行为准则；Lead 每轮对话还会**动态注入实时看板快照**——它不需要先调 `list` 才知道板上有什么，多轮对话也不会因为"忘了看板"重复建任务。
+
+---
+
+## 为长任务而生的执行加固
+
+团队面向的是深度研究、长文档处理这类**一跑几十分钟起步**的任务，执行链路按此加固：
+
+- **执行租约 + 运行期心跳**。任务派发即持有 60 分钟执行租约，成员运行期间后台自动续期；真正失联的任务（进程崩溃、重启）租约到期被判 `stale`，可安全重派——**不会**出现"任务还在跑就被重派、两个实例互相覆盖"的双重执行。
+- **取消即中断**。`cancel` 不只是状态转移：成员子会话注册进流跟踪器，图节点每轮检查停止位，取消后运行中的成员会话在下一个节点边界停下——不再有"取消了还在烧 token 到自然结束"。
+- **人工审批卡点**。建任务时声明 `requireApproval`，成员提交后任务停在 `in_review`，由你在 Teams 页 approve / reject——敏感产出离开团队前先过人。
+- **手动投任务**。任务不非得 Lead 建：Teams 页可以直接建任务指派给某个成员，结果落板上由你查看（没有 Lead 会话要唤醒时，通报自动降级为 no-op）。
+
+---
+
+## 交付物与执行过程可见性
+
+复杂任务的产出不是一段文本，是**文件 + 摘要**：
+
+- 成员用文档渲染工具（docx / pptx / xlsx / pdf）或技能产出文件后，通过 `attach` 把交付物登记到任务上；任务详情渲染**可下载附件列表**，结果通报也会带上附件——链接不再埋在被截断的长文本里。
+- 每个任务详情都有**"查看执行过程"**入口：跳进成员子会话的完整转写——派发信封、逐轮思考、工具调用、中间产物一览无余。任务运行中打开，就是实时打字机直播（断线重连自动回放缓冲）。
+- **任务时间线**：谁在什么时候创建/派发/上报进度/挂附件/审批/取消，逐条落 `mate_team_task_event` 审计表，任务详情按时间线渲染——协同过程有史可查。
+
+---
+
+## Plan-Execute Lead：计划直接变任务板
+
+Lead 不限定 Agent 类型。**ReAct 型 Lead** 用 `team_tasks` 逐条建任务；**Plan-Execute 型 Lead** 更进一步——规划节点产出的计划**整体移交任务板**：
+
+- 计划步骤逐条映射为看板任务，步骤依赖链变成 `blockedBy`——原本严格串行的计划从此**能并行的并行**；
+- 移交后计划停靠（`delegated`），Lead 回合正常结束，等待由派发/通报闭环接管；
+- 全部任务落定后，通报唤醒经**停靠计划恢复门**确定性地路由到计划汇总节点，从任务结果与交付物重建上下文、产出总结——与工具审批"落库停靠、新一轮续跑"同构，不引入检查点机制。
+
+一句话：**会规划的 Lead，规划能力直接变成团队编排能力。**
+
+---
+
+## Teams 页
+
+管理控制台新增 **Teams** 页（`/teams`）：
+
+- **团队管理**：建团队、加/减成员、指定角色；
+- **看板**：按状态分列，事件驱动实时刷新，列内**分页加载**且列头显示**数据库侧统计的真实总数**——千条任务的板也拖不垮页面；
+- **活动横幅**：滚动播报派发、完成、失败等团队事件；
+- **任务详情**：时间线、进度、评论、交付物下载、执行过程入口、approve / reject；
+- **手动建任务**：直接往板上投活。
+
+---
+
+## REST API
+
+管理面 API 全部挂在 `/api/v1/teams` 下：
+
+| 端点 | 说明 |
+|------|------|
+| `GET / POST /api/v1/teams` | 列出 / 创建团队 |
+| `GET / PUT / DELETE /api/v1/teams/{id}` | 团队详情 / 更新 / 删除 |
+| `POST /api/v1/teams/{id}/members` · `DELETE …/members/{agentId}` | 成员增删 |
+| `GET / POST /api/v1/teams/{id}/tasks` | 任务列表（窗口化分页）/ 建任务 |
+| `GET /api/v1/teams/{id}/tasks/stats` | 各状态任务数（数据库侧统计） |
+| `GET /api/v1/teams/{id}/tasks/{taskId}` | 任务详情 |
+| `POST …/tasks/{taskId}/approve · reject · retry · cancel` | 审批 / 重试 / 取消 |
+| `POST …/tasks/{taskId}/comments` | 评论 |
+| `GET …/tasks/{taskId}/events` | 任务时间线 |
+| `GET /api/v1/teams/{id}/events` | 团队级 SSE 事件流（看板实时刷新的数据源） |
+
+所有校验失败都以**可读错误**返回——不是裸 500。
+
+数据落五张表：`mate_agent_team`、`mate_agent_team_member`、`mate_team_task`、`mate_team_task_comment`、`mate_team_task_event`。
+
+---
+
+## 与子员工委派（delegate_agent）怎么选
+
+| | `delegate_agent` | 团队任务板 |
+|---|---|---|
+| 形态 | 一对一临时叫帮手 | 常设团队 + 共享看板 |
+| 并行 | 单点异步 | 成员级并行 + 依赖编排 |
+| 过程 | 黑盒等结果 | 时间线 + 实时旁观 + 交付物 |
+| 中断/恢复 | 随父会话 | 租约、取消中断、重试 |
+| 适合 | 单个子问题外包 | 多角色多步骤的项目型交付 |
+
+两者共存：团队成员在自己的任务里照样可以再 `delegate_agent` 叫帮手。
+
+---
+
+## 接下来读什么
+
+- [Agent 引擎](./agents)——ReAct 与 Plan-Execute 图的工作方式
+- [持久化目标](./goals)——单个员工的跨轮任务跟进
+- [工作流](./workflow)——确定性步骤编排（流程固定时用工作流，流程要临场拆解时用团队）
+- [安全与审批](./security)——工具审批与团队任务审批的关系
diff --git a/mateclaw-server/src/main/resources/docs/zh/wecom-tuning.md b/mateclaw-server/src/main/resources/docs/zh/wecom-tuning.md
index 758bff2d..c71c8e28 100644
--- a/mateclaw-server/src/main/resources/docs/zh/wecom-tuning.md
+++ b/mateclaw-server/src/main/resources/docs/zh/wecom-tuning.md
@@ -216,6 +216,21 @@ MateClaw 在 link 分支检测到 `mp.weixin.qq.com` 后，会自动给模型追
---
+## 进度气泡：长任务不再像卡死（2.0.0+）
+
+2.0.0 之前，企业微信收到消息后只回一条静态"🤔 思考中..."，直到最终答案前**没有任何变化**——30 秒到 3 分钟的长任务普遍被误认为卡死。现在占位气泡是**事件驱动**的：
+
+- **实时工具轨迹**：气泡内容随 agent 执行滚动更新——思考状态、正在调用的工具、已完成的调用与耗时，逐条追加；
+- **按阶段滚动**：每进入一个新阶段（新一轮推理、新的工具调用），气泡原地刷新为当前阶段叙述——一眼看出任务推进到哪了；
+- **原地渐变为答案**：首个真实内容分片到达时取消保活、**复用同一个 stream 槽位**，进度气泡原地变成答案，不留孤儿气泡；
+- **覆写节流**：刷新有最小间隔与"上一次未完成则跳过"双保险，不会触发企业微信的频控。
+
+思考内容与工具轨迹是否展示，仍受渠道编辑页"消息过滤"开关控制——2.0.0 起这两个开关是真正的"过程消息要不要发"，不再只是从最终答案里剥内联标签。
+
+配套的**流式回复管理加固**：stream 槽位的生命周期集中管理，保活、强制收尾、上下文失效各就各位——不再出现"答案发完了气泡还在转"或"槽位悬挂导致下一条消息发不出"的病态。生成的文件（图片、文档）也会通过微信渠道真实送达，而不是只留一个本地链接。
+
+---
+
## 模型行为：假装调用工具
观察：**qwen3.6-plus** 在长上下文 + 工具调用密集的场景下偶发地"懒"——它会用 Markdown 代码块**伪装**自己调了工具，但实际 `toolCallCount=0`：
diff --git a/mateclaw-server/src/main/resources/docs/zh/wiki.md b/mateclaw-server/src/main/resources/docs/zh/wiki.md
index c9db8c0b..700ec1e2 100644
--- a/mateclaw-server/src/main/resources/docs/zh/wiki.md
+++ b/mateclaw-server/src/main/resources/docs/zh/wiki.md
@@ -552,6 +552,12 @@ mate:
`Wiki → 配置 → 实体抽取` 卡片里：打开开关后出现一个标签编辑器（可多选、可搜索、可现场新建）。内置建议就是上面六种，你可以直接敲入自定义类型（比如 `technology`、`law`）按回车加进去。留空则回退到内置六种。类型列表存在 KB 的 `configContent` JSON 的 `entityTypes` 字段里。
+### 关系模式：闭合三元组白名单（2.0.0+）
+
+实体类型限住了"抽什么实体"，但关系一层以前是放开的——模型可以在任意两个实体之间编造任意谓词，边缘实体因为"参与了某条关系"被当作重要实体持久化，稀释你真正关心的那几条确定关系。
+
+现在每个 KB 可以配置一个可选的**关系模式**：一张 `主语类型 → 谓词 → 宾语类型` 的闭合三元组白名单（比如 `person → works_at → organization`）。开启后，抽取**只保留匹配模式的关系与参与这些关系的实体**——模型不再自由发挥，图谱里只有你定义过的关系形态。留空则维持原来的开放抽取。配置同样存进 KB 的 `configContent`，无需迁移。
+
### 在图上看关系
Wiki 图谱视图工具栏上多了**页面图 / 实体图**切换。切到实体图后：
diff --git a/mateclaw-server/src/main/resources/docs/zh/workspaces.md b/mateclaw-server/src/main/resources/docs/zh/workspaces.md
index 1a772b85..5f58fbf9 100644
--- a/mateclaw-server/src/main/resources/docs/zh/workspaces.md
+++ b/mateclaw-server/src/main/resources/docs/zh/workspaces.md
@@ -190,6 +190,12 @@ Wiki KB 的数据**永远不会离开它的工作空间**。工作空间 B 里
每个渠道绑一个 Agent，传递地绑一个工作空间。工作空间 A 里配置的一个钉钉机器人和工作空间 B 里配置的一个钉钉机器人**完全独立**，即使它们被配置成连接同一个钉钉应用（你大概率不想这样，但技术上允许）。
+2.0.0 起，**会话 id 的生成编入渠道标识**——不同工作空间各自新建的同类型渠道，即使面对同一个外部用户，也各有各的会话行；两个工作空间的对话不可能再落进同一条会话。
+
+### 技能（2.0.0）
+
+同名技能可在不同工作空间独立共存：安装查重按工作空间过滤、磁盘目录编入 workspaceId、运行时的 load / 读文件 / 跑脚本只在本会话工作空间（+ builtin + 全局 virtual）范围内解析。一个工作空间的员工读不到、也执行不了另一个工作空间的同名技能。详见[技能系统](./skills)。
+
---
## 工作空间隔离**不**覆盖的
@@ -201,6 +207,15 @@ Wiki KB 的数据**永远不会离开它的工作空间**。工作空间 B 里
---
+## 默认存储路径与桌面本地工具白名单（2.0.0+）
+
+两个来自 issue #512 的落地：
+
+- **默认工作空间存储路径可在界面配置**。每个工作空间的 `base_path` 一直可以在 Security → Workspaces 单独设置，但全局兜底的沙箱根（`mateclaw.workspace.sandbox.root`，默认 `data/workspace`）以前只能改环境变量或 yml。现在它是设置页里的一个**「默认工作空间存储路径」**设置项：新建会话与工作空间的文件集中存放在该路径下；修改只影响之后新建的，**不迁移已有数据**。
+- **桌面端本地工具白名单支持逐条删除**。桌面端允许本地工具访问的目录白名单，以前的管理入口是一个原生对话框，只能"添加"和"停用"，删除 API 是死代码。现在白名单目录在界面里**逐条可见、逐条可删**。
+
+---
+
## 在工作空间之间移动资源
**不直接支持。** 你有两个选项：