From 03b6e9d2d8a46045c0dac83af41e1a82d3f67f69 Mon Sep 17 00:00:00 2001 From: mateaix <7333791@qq.com> Date: Sat, 15 Aug 2026 17:17:51 +0800 Subject: [PATCH] release: v2.1.0 --- README.md | 53 ++++++++++++------ README_zh.md | 55 ++++++++++++------- mateclaw-desktop/package.json | 2 +- .../src/main/resources/docs/en/agents.md | 25 ++++----- .../src/main/resources/docs/en/api.md | 31 ++++++++++- .../src/main/resources/docs/en/channels.md | 14 +++++ .../src/main/resources/docs/en/chat.md | 19 +++++++ .../src/main/resources/docs/en/config.md | 24 ++++---- .../src/main/resources/docs/en/console.md | 8 +-- .../main/resources/docs/en/contributing.md | 12 ++-- .../src/main/resources/docs/en/faq.md | 16 +++--- .../src/main/resources/docs/en/index.md | 6 +- .../src/main/resources/docs/en/intro.md | 10 ++-- .../src/main/resources/docs/en/models.md | 13 +++++ .../src/main/resources/docs/en/quickstart.md | 2 +- .../src/main/resources/docs/en/releases.md | 1 + .../src/main/resources/docs/en/roadmap.md | 20 ++++++- .../src/main/resources/docs/en/security.md | 2 +- .../src/main/resources/docs/en/skills.md | 18 ++++++ .../src/main/resources/docs/en/teams.md | 38 +++++++++++-- .../src/main/resources/docs/en/tools.md | 12 ++++ .../src/main/resources/docs/zh/agents.md | 25 ++++----- .../src/main/resources/docs/zh/api.md | 31 ++++++++++- .../src/main/resources/docs/zh/channels.md | 14 +++++ .../src/main/resources/docs/zh/chat.md | 19 +++++++ .../src/main/resources/docs/zh/config.md | 24 ++++---- .../src/main/resources/docs/zh/console.md | 8 +-- .../main/resources/docs/zh/contributing.md | 12 ++-- .../src/main/resources/docs/zh/faq.md | 16 +++--- .../src/main/resources/docs/zh/index.md | 6 +- .../src/main/resources/docs/zh/intro.md | 10 ++-- .../src/main/resources/docs/zh/models.md | 13 +++++ .../src/main/resources/docs/zh/quickstart.md | 2 +- .../src/main/resources/docs/zh/releases.md | 1 + .../src/main/resources/docs/zh/roadmap.md | 20 ++++++- .../src/main/resources/docs/zh/security.md | 2 +- .../src/main/resources/docs/zh/skills.md | 18 ++++++ .../src/main/resources/docs/zh/teams.md | 38 +++++++++++-- .../src/main/resources/docs/zh/tools.md | 12 ++++ mateclaw-ui/package.json | 2 +- pom.xml | 2 +- 41 files changed, 494 insertions(+), 162 deletions(-) diff --git a/README.md b/README.md index 2f55171b..09182fd6 100644 --- a/README.md +++ b/README.md @@ -30,15 +30,19 @@ --- +> **Latest stable: v2.1.0 — Team Runs, closed skill evolution, and replayable reasoning.** One team request is now one durable `runId` across Chat, Agents, and Teams; skills can mine recurring requests under explicit controls and restore from snapshots; reasoning, tool calls, and observations can be exported in execution order. Read the [v2.1.0 release notes](https://claw.mate.vip/docs/en/releases/2.1.0). + +--- + > **Other personal AI agents are built for one person. MateClaw is the one your IT department can actually sign off on.** > -> Multi-user workspaces. Approval-gated sensitive actions. Full audit trail. Spring Boot Actuator health monitoring. Per-channel error isolation so one chat platform's outage doesn't take down the rest. One JAR on your own machine, zero data egress. +> Multi-user workspaces. Approval-gated sensitive actions. Full audit trail. Spring Boot Actuator health monitoring. Per-channel error isolation so one chat platform's outage doesn't take down the rest. One JAR in your environment; you control persisted data, and task content is sent only to model, channel, or tool services you explicitly configure. > > **And underneath, a real agent harness.** ReAct + Plan-and-Execute on a StateGraph runtime — not a one-shot RAG call dressed up. Tools, Skills, MCP, and ACP converge on one registry with per-employee binding. Sensitive tool calls flow through an approval gate you can actually inspect. Multi-vendor failover keeps the loop running when a provider doesn't. Most AI tools die when their vendor has a bad day. Most forget you the moment the tab closes. Most give you a chatbox and call it a product. -**MateClaw is the whole widget.** One deployment. Reasoning, knowledge, memory, tools, channels — built together, not bolted on. And when your primary model goes down, the next one picks up mid-sentence. +**MateClaw is the whole widget.** One deployment. Reasoning, knowledge, memory, tools, channels — built together, not bolted on. And when your primary model is unavailable, the next healthy provider retries the current request. --- @@ -48,7 +52,7 @@ Most AI tools die when their vendor has a bad day. Most forget you the moment th Primary key expired. Vendor returns 401. Network blip. Quota drained. -Other tools hand you a red error card. MateClaw routes to the next healthy provider — DashScope, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Ollama, LM Studio, MLX, 14+ in total — and the user sees the reply finish. A provider health tracker parks bad vendors in a cooldown window so they don't waste seconds on every turn. +Other tools hand you a red error card. MateClaw tries the next healthy provider in configured order — including built-in and OpenAI-compatible options such as DashScope, OpenAI, Anthropic, Gemini, DeepSeek, Kimi, Ollama, LM Studio, and MLX — and attempts to recover the current request. It returns an error only when the available chain is exhausted. A provider health tracker parks bad vendors in a cooldown window so they don't waste seconds on every turn. You don't write a retry script. You drag providers into priority order in **Settings → Models** and watch the health dashboard fill with green dots as requests route around failures in real time. @@ -56,7 +60,7 @@ You don't write a retry script. You drag providers into priority order in **Sett Upload a PDF, a batch of markdown, a scraped page — raw material in. -MateClaw's **LLM Wiki** digests it into structured pages, builds `[[links]]` between them, and remembers where every sentence came from. Click a citation, see the exact source chunk. Ask a question, the page you get is stitched from the right chunks — with references you can verify. +MateClaw's **LLM Wiki** digests it into structured pages, builds `[[links]]` between them, and preserves traceable citations for generated content. Open the citation drawer to inspect the corresponding source chunk and verify page or answer references. This is the difference between a warehouse and a library. @@ -79,10 +83,10 @@ Same brain. Same memory. Same tools. Different doors. ## What's in the box ### 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. +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 — six built-in templates ship ready (General Assistant · Product Assistant · Research Analyst · Customer Support · Data Analyst · Code Reviewer). **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. +### Team Runs (2.1.0+) +One request, one durable **Team Run**. A stable `runId` links the user's objective, task DAG, worker executions, final synthesis, and deliverables. Chat is the outcome surface, Agents Live groups the workers for real-time observation, and Teams owns history and governance — all three consume the same server projection. Worker conversations no longer flood the normal sidebar; summaries and files lead, while tasks, evidence, approvals, and read-only worker records drill down on demand. Underneath, the 2.0 shared board still provides dependency orchestration, parallel dispatch, prerequisite hand-off, execution leases, cancel-interrupt, and human approval gates. ### 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 @@ -90,7 +94,7 @@ One lead, a crew of employees, one **shared task board**. Tell the lead a goal a - **Memory lifecycle** — post-conversation extraction, scheduled consolidation, Dreaming workflows. Workflows can also write directly into an employee's `MEMORY.md` via the `write_memory` step ### Skills · MCP · ACP — three ways to extend capability -- **SKILL.md packages** — manifest + prompt + tool list + **LESSONS.md (gets smarter the more you use it)**. Eight starter templates plus a five-step creation wizard, with **Pre-flight checks** that tell you what's missing before install +- **SKILL.md packages** — manifest + prompt + tool list + **LESSONS.md**. In 2.1, reflection and cross-session recurring-request mining can produce reusable improvements; routine promotion, constrained auto-binding, curator handover/governance, origin policy, snapshots, and restore points keep evolution observable, workspace-scoped, and reversible. Eight starter templates plus a five-step creation wizard, with **Pre-flight checks** before install - **MCP** — stdio / SSE / Streamable HTTP, plug into any external tool server. **Per-employee binding** (1.3.0+) means a tool you install for one employee doesn't bleed into another's toolbox - **ACP** — bring top-tier coding agents like Claude Code and Codex in as employees, auto-bridged to skill cards with wrapper tools - **Tool Guard** — RBAC + approval flow + path protection. Capability needs boundaries @@ -101,7 +105,7 @@ One lead, a crew of employees, one **shared task board**. Tell the lead a goal a - **Wiki Transformations** — Wiki stops being retrieval-only. User-authored templates run against raw materials or existing pages, with cross-material map-reduce aggregation, reverse-citation extraction, JSON output mode, and per-template model picker ### You see what every employee is doing -**Admin Runtime Console** (`Settings → System → Runtime`) — who's running, what step they're on, how many tokens, one-click force-recycle when stuck. Streaming is staged honestly (thinking / tool / answer), per-event SSE IDs make reconnects safe, multi-employee delegation no longer fights itself, long tasks demand evidence-grounded answers. +**Admin Runtime Console** (`Settings → System → Runtime`) — who's running, what step they're on, how many tokens, one-click force-recycle when stuck. Streaming is staged honestly (thinking / tool / answer), each reasoning iteration keeps its real position and wall-clock duration, and linear trajectory export lays out reasoning, calls, observations, and answers for review. Per-event SSE IDs make reconnects safe; Team Runs group member work under one live execution. ### Multimodal creation Text-to-speech · Speech-to-text · Image · Music · Video · 3D. First-class, not add-ons. **Sidecar routing** (1.3.0+) means a text-only main model + an image attachment no longer dead-ends — a configured vision model describes the image, and the main model answers. **Image edit** lands too: refer to an earlier conversation attachment by `msg::` and ask the model to recolor or restyle it. Four **document-generation tools** (`DocxRenderTool` / `XlsxRenderTool` / `PptxRenderTool` / `PdfRenderTool`) render Markdown straight to Office files inside the JVM — no subprocess, no Office install. @@ -110,15 +114,15 @@ Text-to-speech · Speech-to-text · Image · Music · Video · 3D. First-class, A flagship *scene*, not a tool — a seeded "Content Studio" employee turns one sentence into a publishable post: pick-topic → research → draft → illustrate → **de-AI** → lay out → deliver. **WeChat Official Account (公众号)** articles land in your draft box as inline-style HTML with body images uploaded into WeChat; **Xiaohongshu (小红书)** notes package as ≥3 vertical 3:4 cards with an online preview. De-AI-ification runs against a **measurable AI-trace score**; every delivery is compliance-scanned and logged to a **content calendar** that dedups by topic fingerprint. ### Enterprise-ready -RBAC + JWT. **Personal Access Tokens** for headless scripts and CI. **HMAC-SHA-256 outbound webhook signing**. **Distributed Cron lock** so multi-instance deployments don't double-fire. Full audit trail. Flyway-managed schema that auto-heals on upgrade. One JAR to ship. MySQL in production, H2 for dev — nothing to change in your code. +RBAC + JWT. **Personal Access Tokens** for headless scripts and CI. **HMAC-SHA-256 outbound webhook signing**. **Distributed Cron lock** so multi-instance deployments don't double-fire. Full audit trail. Flyway-managed schema. One JAR to ship. H2 for development; the public Docker stack defaults to PostgreSQL 16, the MySQL profile remains supported, and the Kingbase driver is opt-in. --- ## AI is becoming infrastructure -On March 2, 2026, Claude went dark for 4 hours across API, web, and mobile. Three weeks later, another 5 hours. Every company that bet their AI strategy on a single vendor spent those outages staring at red error cards. +Model providers rate-limit, networks fail, keys expire, and services become temporarily unavailable. Betting every AI capability on one provider turns an upstream incident into your own outage. -This is the same shift databases went through around 2010 and cloud went through around 2018: the winning layer stops being tied to one supplier. **57% of companies now run AI agents in production.** None of them want one vendor's bad day to become their bad day. +Once AI enters production, the stable layer should not be tied to one supplier. MateClaw absorbs that uncertainty into one runtime through provider priorities, health tracking, cooldown, and failover. **MateClaw is that layer — built the Spring Boot way.** @@ -138,7 +142,7 @@ This is the same shift databases went through around 2010 and cloud went through **OpenClaw and Hermes Agent are excellent personal AI platforms** — pick either if you're running one user on one laptop, building your own agent from CLI, and treating everything as config files to hand-tune. Both have bigger communities than MateClaw today. -**MateClaw is the version built for teams.** RBAC per digital employee, per model, per tool. An approval flow that pauses risky actions for review. Full audit trail. The Admin Runtime Console gives one operator real-time visibility into 50 employees running across 14 vendors — stuck? force-recycle in one click. Spring Boot inside — drop-in for any Java shop already running production services. +**MateClaw is the version built for teams.** Digital employees, models, and tools sit behind permissions and workspace boundaries. Approval flows can pause risky actions for review, and key operations enter the audit trail. The Admin Runtime Console centralizes active employee and provider state with force-recycle for stuck runs. Spring Boot inside — a natural fit for Java shops already running production services. Same "whole widget" philosophy. Different center of gravity. @@ -153,7 +157,7 @@ mvn spring-boot:run # http://localhost:18088 # Frontend cd mateclaw-ui -pnpm install && pnpm dev # http://localhost:5173 +npm install && npm run dev # http://localhost:5173 ``` Login: `admin` / `admin123` @@ -192,9 +196,12 @@ Download from [GitHub Releases](https://github.com/mateaix/mateclaw/releases). B mateclaw/ ├── mateclaw-server/ Spring Boot 3.5 backend (Spring AI Alibaba, StateGraph runtime) ├── mateclaw-ui/ Vue 3 + TypeScript admin SPA (built into the server JAR) +├── mateclaw-desktop/ Electron desktop app (local-embedded / remote-centralized) ├── mateclaw-webchat/ Embeddable chat widget (UMD / ES bundles) ├── mateclaw-plugin-api/ Java SDK for third-party capability plugins ├── mateclaw-plugin-sample/ Reference plugin implementation +├── mateclaw-plugin-mem0/ Optional Mem0 memory-provider plugin +├── mateclaw-plugin-search-sample/ Search Provider SPI example ├── docker-compose.yml └── .env.example ``` @@ -206,10 +213,10 @@ 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 · Team task board (2.0.0+) | +| Digital Employee Runtime | StateGraph · ReAct + Plan-Execute · Role / Goal / Backstory · closed skill evolution · Team Run + shared task board (2.1.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) | +| Database | H2 (dev) · PostgreSQL 16 (Docker default) · MySQL 8.0+ (supported) · Kingbase (opt-in driver) | | Auth | Spring Security + JWT | | Frontend | Vue 3 · TypeScript · Vite · Element Plus · TailwindCSS 4 | | Desktop | Electron · electron-updater · JRE 21 (bundled) | @@ -223,7 +230,17 @@ 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: +**v2.1.0 (shipped 2026-08-15)** — from “a board full of tasks” to **one governable team run**: + +- **Unified Team Runs** — one `runId` links request, task DAG, worker conversations, events, final synthesis, and deliverables; Chat delivers outcomes, Agents observes live work, Teams governs history +- **Closed skill evolution** — reflection + recurring-request mining + promotion + constrained auto-binding + curator governance + snapshots/restore, conservative by default and isolated per workspace +- **Replayable execution** — live `` extraction, every reasoning iteration in emission order with real duration, superseded narration, and linear trajectory export +- **Capabilities reach operations** — proactive IM push, targeted Cron delivery, model-specific context windows, progressive tool disclosure, and tool-backed action completion +- **Reliability pass** — hardened browser refs/navigation/waits, WebChat/SSE cleanup and upstream idle timeout, Feishu progress, Qwen3-ASR HTTP, batch session deletion, date-partitioned files, and safe 64-bit ids + +Full story in the [v2.1.0 release notes](https://claw.mate.vip/docs/en/releases/2.1.0). + +**v2.0.0 (shipped 2026-07-31)** — 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 @@ -274,7 +291,7 @@ Full story in the [v1.7.0 release notes](https://claw.mate.vip/docs/en/releases/ git clone https://github.com/mateaix/mateclaw.git cd mateclaw cd mateclaw-server && mvn clean compile -cd ../mateclaw-ui && pnpm install && pnpm dev +cd ../mateclaw-ui && npm install && npm run dev ``` --- diff --git a/README_zh.md b/README_zh.md index 63240396..9d552d96 100644 --- a/README_zh.md +++ b/README_zh.md @@ -30,15 +30,19 @@ --- +> **最新稳定版：v2.1.0 —— Team Run、Skill 自进化闭环与可回放执行。** 一次团队请求现在以一个持久化 `runId` 贯穿 Chat、Agents 与 Teams；技能可在显式开关和工作空间隔离下发现重复请求、晋升并从快照恢复；推理、工具调用、观察与回答可按执行顺序导出。详见 [v2.1.0 更新记录](https://claw.mate.vip/docs/zh/releases/2.1.0)。 + +--- + > **别的 AI 助手是给一个人用的。MateClaw 是公司允许部署的那一个。** > -> 多用户工作空间。敏感操作走审批。完整审计日志。Spring Boot Actuator 健康监控。单个渠道挂掉不影响其他渠道的错误隔离。一个 JAR 包跑在自己机器上，数据不出门。 +> 多用户工作空间。敏感操作走审批。完整审计日志。Spring Boot Actuator 健康监控。单个渠道挂掉不影响其他渠道的错误隔离。一个 JAR 包跑在自己的环境里；持久化数据由你掌控，任务所需内容只会发送到你主动配置的模型、渠道或工具服务。 > > **底下是个真 agent harness。** ReAct + Plan-and-Execute 跑在 StateGraph 运行时上——不是一次 RAG 调用披件外套。工具 · 技能 · MCP · ACP 收敛进同一个注册表，每位员工独立绑定。敏感工具调用走可审计的审批闸门。多厂商故障转移让循环在某家供应商挂掉时也不停。 大多数 AI 工具一到厂商抽风那天就两手一摊。关一次标签页就忘了你是谁。给你一个聊天框，就敢叫产品。 -**MateClaw 是完整的一整套。** 一次部署——推理、知识、记忆、工具、多渠道入口，从第一天就一起设计，不是事后拼接。主模型挂了，下一家接着把这句话说完。 +**MateClaw 是完整的一整套。** 一次部署——推理、知识、记忆、工具、多渠道入口，从第一天就一起设计，不是事后拼接。主模型不可用时，系统会按优先级改由下一家健康供应商重新完成当前请求。 --- @@ -48,7 +52,7 @@ Key 过期。厂商返回 401。网络抖动。配额耗尽。 -别的工具丢你一张红色错误卡。MateClaw 自动切到下一家健康的供应商——DashScope、OpenAI、Anthropic、Gemini、DeepSeek、Kimi、Ollama、LM Studio、MLX，共 14+ 家——用户只会看到回答正常完成。内置的 **Provider Health Tracker** 会把连续失败的供应商放进冷却窗口，避免每一轮对话都白白撞壁。 +别的工具丢你一张红色错误卡。MateClaw 会按配置顺序尝试下一家健康供应商——DashScope、OpenAI、Anthropic、Gemini、DeepSeek、Kimi、Ollama、LM Studio、MLX 等内置或 OpenAI 兼容供应商——尽可能恢复当前请求；仅当可用链路全部失败时才返回错误。内置的 **Provider Health Tracker** 会把连续失败的供应商放进冷却窗口，避免每一轮对话都白白撞壁。 你不用写重试脚本。在 **设置 → 模型** 里把供应商拖成你想要的优先顺序，健康面板实时亮起一排绿点——请求绕着故障流过去。 @@ -56,7 +60,7 @@ Key 过期。厂商返回 401。网络抖动。配额耗尽。 上传 PDF、一批 markdown、抓下来的网页——原始材料进去。 -MateClaw 的 **LLM Wiki** 把它消化成结构化页面，页面之间自己长出 `[[链接]]`，每一句话都记得来自哪里。点开引用抽屉，就能看到原始 chunk。问一个问题，得到的页面是从对应片段拼出来的——带可核对的出处。 +MateClaw 的 **LLM Wiki** 把它消化成结构化页面，页面之间自己长出 `[[链接]]`，生成内容保留可追踪引用。点开引用抽屉，就能看到对应的原始 chunk；页面与回答中的引用可以回到来源核对。 这是**仓库**和**图书馆**的区别。 @@ -79,10 +83,10 @@ MateClaw 的 **LLM Wiki** 把它消化成结构化页面，页面之间自己长 ## 盒子里有什么 ### 数字员工，不是聊天机器人 -你雇佣员工，不是开聊天框。每位有**角色**、**目标**、**背景故事**，像素艺术头像、专属配色——5 个职业模板（产品研究员 · 客户支持 · 知识管理员 · 数据分析师 · 行政助理）开箱可用。**ReAct** 做迭代推理，**Plan-and-Execute** 做复杂多步任务，员工之间可以并行委派。动态上下文裁剪、智能截断、僵死流清理——让长对话真正能用的那些"不起眼"的基础设施。 +你雇佣员工，不是开聊天框。每位有**角色**、**目标**、**背景故事**，像素艺术头像与专属配色——6 个内置模板（通用助手 · 产品助理 · 研究分析师 · 客服助理 · 数据分析师 · 代码审查员）开箱可用。**ReAct** 做迭代推理，**Plan-and-Execute** 做复杂多步任务，员工之间可以并行委派。动态上下文裁剪、智能截断、僵死流清理——让长对话真正能用的那些“不起眼”的基础设施。 -### 团队协作（2.0.0+） -一个 Lead 带一群员工，围着一块**共享任务板**干活。你对 Lead 说一句目标，它拆成任务上板（`blockedBy` 声明依赖）；派发引擎把任务并行分给成员，前置结果自动传给下游，完成结果自动通报回 Lead 汇总。执行租约 + 心跳杜绝双重执行，**取消即中断**正在跑的成员会话，敏感任务停在 `in_review` 等人批。交付物（docx / pptx / xlsx / pdf）登记到任务可下载，任务时间线记录全程，还能跳进任意成员的子会话看它逐字执行。Plan-Execute 型 Lead 的计划**整体移交任务板**——会规划的 Lead，规划能力就是编排能力。 +### Team Run（2.1.0+） +一次请求对应一个持久化的 **Team Run**。稳定的 `runId` 串起用户目标、任务 DAG、成员执行、最终汇总与交付物。Chat 是成果交付面，Agents Live 按运行聚合成员并展示实时状态，Teams 管理历史与治理；三处读取同一份服务端投影。成员子会话不再挤进普通会话列表，摘要和文件优先展示，任务、证据、审批与只读成员记录按需下钻。底层继续使用 2.0 的共享任务板，保留依赖编排、并行派发、前置结果传递、执行租约、取消中断和人工审批卡点。 ### 知识与记忆 - **LLM Wiki** — 原始材料消化成有链接、带引用的结构化页面；**热点缓存**自动注入到员工的 system prompt。**加工器引擎**（1.3.0+）把 Wiki 从"搜索索引"升级为"处理流水线" @@ -90,7 +94,7 @@ MateClaw 的 **LLM Wiki** 把它消化成结构化页面，页面之间自己长 - **记忆生命周期** — 对话后自动提取 · 定时整理 · Dreaming 工作流。工作流也可以通过 `write_memory` step 直接写进员工的 `MEMORY.md` ### 技能 · MCP · ACP — 三种"接外部能力"的方式 -- **SKILL.md 技能包** — 一份 manifest + prompt + 工具列表 + **LESSONS.md（用得越多越聪明）**。8 个起步模板 + 5 步创作向导，安装前自动跑 **Pre-flight 检查**告诉你缺什么 +- **SKILL.md 技能包** — 一份 manifest + prompt + 工具列表 + **LESSONS.md**。2.1 可通过对话反思与跨会话重复请求挖掘形成可复用改进，并以候选晋升、受约束自动绑定、curator 治理、来源策略、快照和恢复点保证过程可观察、按工作空间隔离且可回滚；所有自动能力均由独立开关控制。另有 8 个起步模板、5 步创作向导和安装前 **Pre-flight 检查** - **MCP** — stdio / SSE / Streamable HTTP 三种传输，接入任意外部工具服务器。**每位员工独立绑定**（1.3.0+）——一位员工装的工具不会渗到其他人的工具栏里 - **ACP** — 把 Claude Code、Codex 这种顶级编码 Agent 以"员工"身份接入，桥接成技能卡 + 包装工具 - **Tool Guard** — RBAC + 审批流 + 文件路径保护。能力必须有边界 @@ -101,24 +105,24 @@ MateClaw 的 **LLM Wiki** 把它消化成结构化页面，页面之间自己长 - **Wiki 加工器** — Wiki 不再只是被动检索。用户自定义模板对原料或现有页面跑模板，跨原料 map-reduce 聚合，reverse-citation 绑定到源 chunk，JSON 输出 + 可选 JSON Schema，每个模板独立选模型 ### 你看得见每位员工正在干什么 -**Admin 运行时控制台**（`后台 → 系统 → 运行时`）——谁在跑、跑到哪一步、占多少 token、卡住了一键回收。流式分阶段显示（思考 / 工具 / 回答），SSE 每事件 ID 支持安全重连，多员工协作不打架，长任务必须有真实证据才回答。 +**Admin 运行时控制台**（`后台 → 系统 → 运行时`）——谁在跑、跑到哪一步、占多少 token、卡住了一键回收。流式阶段如实区分思考 / 工具 / 回答；每轮推理保留真实发生顺序，界面显示实际耗时，线性 trajectory 导出则按顺序展开推理、调用、观察与回答。SSE 每事件 ID 支持安全重连，Team Run 将成员工作聚合到同一次运行下。 ### 多模态创作 语音合成 · 语音识别 · 图片 · 音乐 · 视频 · 3D。一等公民，不是附加插件。**多模态旁路**（1.3.0+）让纯文本主模型遇到图片附件时自动调用配置好的视觉模型转描述，主对话保持便宜。**图像编辑**也到位：用 `msg::` 引用会话里更早的某张图，让模型改色、改风格。**4 个文档生成工具**（`DocxRenderTool` / `XlsxRenderTool` / `PptxRenderTool` / `PdfRenderTool`）在 JVM 内把 Markdown 直接渲染成 Office 文件——不 fork 子进程、不依赖 npm、不需要装 Office。 ### 内容工作室（1.8.0+） -一个招牌*场景*,不是工具——预置的「内容工作室」员工把一句话变成可发布成品:选题 → 搜集 → 成文 → 配图 → **去 AI 化** → 排版 → 交付。**微信公众号(公众号)** 文章以内联样式 HTML 躺进你的草稿箱,正文图自动上传进微信;**小红书** 笔记打包成 ≥3 张竖版 3:4 卡片并在线预览。去 AI 化对着一个**可度量的 AI 痕迹评分**跑;每次交付都被合规扫描并记进一个按选题指纹去重的**内容日历**。 +一个招牌*场景*，不是工具——预置的「内容工作室」员工把一句话变成可发布成品：选题 → 搜集 → 成文 → 配图 → **去 AI 化** → 排版 → 交付。**微信公众号（公众号）**文章以内联样式 HTML 进入草稿箱，正文图自动上传到微信；**小红书**笔记打包成 ≥3 张竖版 3:4 卡片并在线预览。去 AI 化围绕一个**可度量的 AI 痕迹评分**运行；每次交付都经过合规扫描，并记入按选题指纹去重的**内容日历**。 ### 企业就绪 -RBAC + JWT。**Personal Access Token** 给无人值守脚本和 CI 用。**Webhook 出站 HMAC-SHA-256 签名**。**Cron 分布式锁**多实例不双发。完整审计事件流。Flyway 管理数据库 schema，升级时自愈。一个 JAR 交付。生产用 MySQL，开发用 H2，代码零改动。 +RBAC + JWT。**Personal Access Token** 给无人值守脚本和 CI 使用。**Webhook 出站 HMAC-SHA-256 签名**。**Cron 分布式锁**避免多实例重复执行。完整审计事件流。Flyway 管理数据库 schema。一个 JAR 交付。开发环境可用 H2；公开 Docker 栈默认使用 PostgreSQL 16，同时保留 MySQL profile，Kingbase 驱动为按需启用。 --- ## AI 正在变成基础设施 -2026 年 3 月 2 日，Claude 全球宕机 **4 小时**——API、Web、移动端同时黑屏。三周后又来一次，**5 小时**。每一家把 AI 战略押在单一厂商身上的公司，那几个小时只能盯着红色错误卡。 +模型供应商会限流，网络会抖动，Key 会过期，服务也可能临时不可用。把所有 AI 能力押在单一供应商上，会让上游故障直接变成自己的业务故障。 -这和 2010 年数据库走过的路、2018 年云走过的路**是同一个转弯**：赢的那一层，不再绑在一家供应商身上。**57% 的公司已经把 AI agent 推进生产**——没有一家希望某个厂商的坏日子变成自己的坏日子。 +当 AI 进入生产环境，稳定的一层不应绑定在一家供应商身上。MateClaw 通过供应商优先级、健康追踪、冷却与故障转移，把这种不确定性收进统一运行时。 **MateClaw 就是那一层——用 Spring Boot 方式盖的。** @@ -138,7 +142,7 @@ RBAC + JWT。**Personal Access Token** 给无人值守脚本和 CI 用。**Webho **OpenClaw 和 Hermes Agent 是优秀的个人 AI 平台**——如果你是一个人、一台笔记本、习惯从 CLI 搭自己的 agent、所有东西都靠手工配置文件调优，选它们没问题。两家的社区规模今天都大于 MateClaw。 -**MateClaw 是那个给团队用的版本。** 每位数字员工、每个模型、每个工具都有 RBAC。危险动作自动暂停等审批。完整审计事件流。Admin 运行时控制台让一个运维能实时看到 50 位员工跑在 14 家供应商上的状态——卡住了一键回收。底座是 Spring Boot——任何一家已经在生产跑 Java 服务的公司可以直接并入。 +**MateClaw 是那个给团队用的版本。** 数字员工、模型与工具都纳入权限和工作空间边界。危险动作可暂停等待审批，关键操作进入审计事件流。Admin 运行时控制台集中展示正在执行的员工与供应商状态，卡住时可回收。底座是 Spring Boot，适合并入已有 Java 服务体系。 **同一套"完整一整套"哲学，不同的重心。** @@ -153,7 +157,7 @@ mvn spring-boot:run # http://localhost:18088 # 前端 cd mateclaw-ui -pnpm install && pnpm dev # http://localhost:5173 +npm install && npm run dev # http://localhost:5173 ``` 默认登录：`admin` / `admin123` @@ -192,9 +196,12 @@ docker compose up -d # http://localhost:18080 mateclaw/ ├── mateclaw-server/ Spring Boot 3.5 后端（Spring AI Alibaba · StateGraph 运行时） ├── mateclaw-ui/ Vue 3 + TypeScript 管理 SPA（构建产物打进后端 JAR） +├── mateclaw-desktop/ Electron 桌面端（本地内嵌 / 远程集中双模式） ├── mateclaw-webchat/ 网页嵌入式聊天组件（UMD / ES bundle） ├── mateclaw-plugin-api/ 第三方能力插件的 Java SDK ├── mateclaw-plugin-sample/ 参考插件实现 +├── mateclaw-plugin-mem0/ 可选 Mem0 记忆 Provider 插件 +├── mateclaw-plugin-search-sample/ 搜索 Provider SPI 示例 ├── docker-compose.yml └── .env.example ``` @@ -206,10 +213,10 @@ mateclaw/ | 层次 | 技术 | |---|---| | 后端 | Spring Boot 3.5 · Spring AI Alibaba 1.1 · MyBatis Plus · Flyway | -| 数字员工运行时 | StateGraph · ReAct + Plan-Execute · 角色 / 目标 / 背景故事 · LESSONS 自我进化 · 团队任务板（2.0.0+）| +| 数字员工运行时 | StateGraph · ReAct + Plan-Execute · 角色 / 目标 / 背景故事 · Skill 自进化闭环 · Team Run + 共享任务板（2.1.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+（生产）| +| 数据库 | H2（开发）· PostgreSQL 16（Docker 默认）· MySQL 8.0+（支持）· Kingbase（按需驱动）| | 认证 | Spring Security + JWT | | 前端 | Vue 3 · TypeScript · Vite · Element Plus · TailwindCSS 4 | | 桌面端 | Electron · electron-updater · 内嵌 JRE 21 | @@ -223,7 +230,17 @@ mateclaw/ ## 路线图 -**v2.0.0（2026-07-26 发布）** — 从"一个能干活的人"到"一支能协作的队伍"：**Agent 团队**成为常设编制，围着一块共享任务板干活： +**v2.1.0（2026-08-15 发布）** —— 从“一块摆满任务的看板”到**一次可治理的团队运行**： + +- **统一 Team Run** —— 一个 `runId` 串起请求、任务 DAG、成员会话、事件、最终汇总与交付物；Chat 交付成果，Agents 观察实时执行，Teams 管理历史与治理 +- **Skill 自进化闭环** —— 对话反思、重复请求挖掘、候选晋升、受约束自动绑定、curator 治理、快照与恢复；默认保守、显式控制并按工作空间隔离 +- **可回放执行** —— 实时提取内联 ``，每轮推理按发生顺序展示实际耗时，保留被后续工具调用替代的阶段旁白，并可导出线性 trajectory +- **能力进入日常运营** —— 主动 IM 推送、Cron 定向投递、模型级上下文窗口、渐进式工具披露，以及基于实际工具调用结果的行动完成检查 +- **可靠性加固** —— 浏览器 ref / 导航 / 等待、WebChat 与 SSE 清理及上游空闲超时、飞书进度、Qwen3-ASR HTTP、会话批量删除、文件按日分区和 64 位 ID 精度保护 + +完整内容见 [v2.1.0 更新记录](https://claw.mate.vip/docs/zh/releases/2.1.0)。 + +**v2.0.0（2026-07-31 发布）** —— 从“一个能干活的人”到“一支能协作的队伍”：**Agent 团队**成为常设编制，围绕共享任务板工作： - **Agent 团队与共享任务板** — 团队 / 角色（lead · member · reviewer）、八状态看板、`blockedBy` 依赖编排、成员级并行派发、前置结果自动传递、结果通报唤醒 Lead；Teams 页事件驱动实时看板 + 活动横幅 + 任务时间线 + 交付物下载 + 手动投任务 - **为长任务加固的执行链** — 执行租约 + 运行期心跳防双重执行、取消即真实中断、`in_review` 审批卡点、失败/过期可重试 @@ -274,7 +291,7 @@ mateclaw/ git clone https://github.com/mateaix/mateclaw.git cd mateclaw cd mateclaw-server && mvn clean compile -cd ../mateclaw-ui && pnpm install && pnpm dev +cd ../mateclaw-ui && npm install && npm run dev ``` --- diff --git a/mateclaw-desktop/package.json b/mateclaw-desktop/package.json index 0b4cff32..336d6171 100644 --- a/mateclaw-desktop/package.json +++ b/mateclaw-desktop/package.json @@ -1,6 +1,6 @@ { "name": "mateclaw-desktop", - "version": "2.1.0-SNAPSHOT", + "version": "2.1.0", "description": "MateClaw Desktop - AI Assistant powered by Spring AI Alibaba", "author": "MateClaw Team", "license": "Apache-2.0", diff --git a/mateclaw-server/src/main/resources/docs/en/agents.md b/mateclaw-server/src/main/resources/docs/en/agents.md index 3a66f9ef..6a02f916 100644 --- a/mateclaw-server/src/main/resources/docs/en/agents.md +++ b/mateclaw-server/src/main/resources/docs/en/agents.md @@ -38,31 +38,26 @@ You can have many employees. Each one is specialized. You give them different jo | **Max iterations** | How many reasoning loops are allowed before forced convergence | | **Enabled flag** | Off switch | -Notice what's *not* here: the model. A single global default model (set in `Settings → Models`) is used for every agent at runtime. The `model_name` field on the agent row is a legacy artifact — it's ignored. This is intentional: swapping models across your whole deployment is one click, not thirty. +Models resolve in this order: **conversation pin → agent model override → global default**. A conversation may temporarily pin an enabled provider/model, and an agent may select its own primary model; a blank agent choice inherits the global default. If a pin is later disabled or removed, runtime falls back to the agent override or global default instead of failing the conversation. Each agent can also maintain an ordered provider/model failover preference chain. --- ## Templates: hire a coworker who already knows the job -You don't start from scratch. `Digital Employees → New` opens a two-tier template picker. +You do not have to start from scratch. `Digital Employees → New` opens a picker populated from the server's `classpath:templates/*.json`; you can also skip templates and continue to the blank form. -### 5 career templates (recommended) +### 6 built-in templates (recommended) Each one ships with a role, goal, backstory, the right toolset, a pixel-art avatar, and a color that belongs to the role. **Open one, it works:** -- **Product Researcher** — competitive scans, market tracking, interview synthesis -- **Customer Support** — catch every question, look it up in the KB, escalate what they can't resolve -- **Knowledge Curator** — feed scattered material into the LLM Wiki, maintain bidirectional links, periodic consolidation +- **General Assistant** — search, writing, analysis, and everyday work +- **Product Assistant** — clarify users, scenarios, and requirements before shaping product decisions +- **Research Analyst** — decompose complex research with web search and Wiki context +- **Customer Support** — empathize, search available knowledge, solve or escalate - **Data Analyst** — query datasources, run SQL, build charts, write conclusions -- **Executive Assistant** — calendar, email drafts, cross-tool coordination +- **Code Reviewer** — inspect code, identify issues, and recommend improvements -### Generic templates (blank or half-finished) - -- **General Assistant** — the default chat employee -- **Research / Code / Writing / Knowledge Curator / Data Analyst** — semi-finished, organized by purpose -- **Custom** — fully blank, if you know exactly what you want - -Pick one, give them a name, adjust the role and goal, save. **Working coworker in under a minute.** Every field is editable after creation. +Selecting a template creates the corresponding agent immediately; skipping opens the fully editable custom form. Name, role, goal, model, skills, tools, and knowledge-base scope remain editable after creation. --- @@ -235,7 +230,7 @@ Not every question deserves deep reasoning, but some do. MateClaw lets you turn `Digital Employees → New`: -1. Pick a template (one of the 5 career templates, a generic template, or Custom) +1. Pick a built-in template, or start from a custom configuration 2. Name them, choose an avatar (pixel-art library, or upload your own) 3. Write a one-sentence **Role**, a one-sentence **Goal**, a few-sentence **Backstory** 4. Write a one-line **employee-card tagline** — the self-introduction shown on the card diff --git a/mateclaw-server/src/main/resources/docs/en/api.md b/mateclaw-server/src/main/resources/docs/en/api.md index f65379a4..8e5a00a3 100644 --- a/mateclaw-server/src/main/resources/docs/en/api.md +++ b/mateclaw-server/src/main/resources/docs/en/api.md @@ -337,7 +337,7 @@ Mounted at `/api/v1/conversations`, `@Tag("会话管理")`. Isolated per logged- Key `MessageVO` fields: `id`, `role`, `content`, `toolName`, `status`, `metadata` (object, contains toolCalls etc.), `promptTokens` / `completionTokens`, `runtimeModel` / `runtimeProvider`, `contentParts`, `createTime`. -**Per-conversation ops**: `PUT .../title` (rename), `PUT .../pin` (`{pinned:bool}`), `PUT .../model` (switch model `{modelProvider, modelName}`), `DELETE .../messages` (clear messages, keep the conversation), `DELETE .../{conversationId}` (delete conversation), `POST /batch-delete` (`{conversationIds: [...]}`), `GET .../status` (stream status `{streamStatus}`). +**Per-conversation ops**: `PUT .../title` (rename), `PUT .../pin` (`{pinned:bool}`), `PUT .../model` (switch model `{modelProvider, modelName}`), `DELETE .../messages` (clear messages, keep the conversation), `DELETE .../{conversationId}` (delete conversation), `POST /batch-delete` (`{conversationIds: [...]}`, at most 200 unique ids), `GET .../status` (stream status `{streamStatus}`), and `GET .../trajectory` (plain-text export in segment emission order). > Every op first checks `isConversationOwner(conversationId, username)`; non-owners get 403. @@ -350,6 +350,7 @@ Mounted at `/api/v1/models`, `@Tag("模型配置管理")`. `GET /` and `GET /cat - `GET /api/v1/models/default` — global default model (`R`). - `GET /api/v1/models/active` — current active model `{activeLlm: {provider, modelName}}`. - `PUT /api/v1/models/active` — set the active model. +- `PUT /api/v1/models/{providerId}/models/context-window` — a global admin sets one `modelId`'s `maxInputTokens`; null or non-positive clears the override. ### Audit events (pagination example) @@ -440,6 +441,20 @@ Total routes extracted: 406. | `PUT` | `/api/v1/conversations/{conversationId}/pin` | `Set Pinned` | | `GET` | `/api/v1/conversations/{conversationId}/status` | `Get Stream Status` | | `PUT` | `/api/v1/conversations/{conversationId}/title` | `Rename` | +| `GET` | `/api/v1/conversations/{conversationId}/trajectory` | `Export plain-text trajectory (conversation owner)` | + +### Team Runs (2.1.0+) + +| Method | Path | Purpose / handler | +|---|---|---| +| `GET` | `/api/v1/team-runs/{runId}` | `Get one Team Run (viewer+)` | +| `POST` | `/api/v1/team-runs/{runId}/cancel` | `Cancel the run, optional {reason} (admin)` | +| `GET` | `/api/v1/teams/{teamId}/runs` | `List team runs, optional activeOnly (viewer+)` | +| `GET` | `/api/v1/teams/{teamId}/runs/page` | `Cursor/limit page of team runs, optional activeOnly (viewer+)` | +| `GET` | `/api/v1/conversations/{conversationId}/team-runs` | `List runs linked to a lead conversation (viewer+)` | +| `GET` | `/api/v1/conversations/{conversationId}/team-runs/page` | `Cursor/limit page of conversation runs (viewer+)` | + +Every endpoint scopes reads/writes to the current workspace (`X-Workspace-Id`, default workspace 1 when omitted); consumers should keep Snowflake ids as strings. ### Agents @@ -628,6 +643,7 @@ Total routes extracted: 406. | `POST` | `/api/v1/models/{providerId}/disable` | `Disable Provider` | | `POST` | `/api/v1/models/{providerId}/discover` | `Discover Models` | | `POST` | `/api/v1/models/{providerId}/discover/apply` | `Apply Discovered Models` | +| `PUT` | `/api/v1/models/{providerId}/models/context-window` | `Set/clear one model's maximum input tokens (global admin)` | | `POST` | `/api/v1/models/{providerId}/enable` | `Enable Provider` | | `DELETE` | `/api/v1/models/{providerId}/models` | `Remove Provider Model` | | `POST` | `/api/v1/models/{providerId}/models` | `Add Provider Model` | @@ -711,6 +727,19 @@ Total routes extracted: 406. | `GET` | `/api/v1/skills/curator/reports/{runId}` | `Curator Report` | | `POST` | `/api/v1/skills/curator/resume` | `Curator Resume` | | `GET` | `/api/v1/skills/curator/status` | `Curator Status` | +| `POST` | `/api/v1/skills/curator/consolidate` | `Enable/disable the curator consolidation pass` | +| `GET` | `/api/v1/skills/curator/managed` | `List skills under autonomous curation` | +| `GET` | `/api/v1/skills/curator/unmanaged` | `List skills outside autonomous curation` | +| `POST` | `/api/v1/skills/curator/adopt` | `Bulk handover to curation; body is a string-id array` | +| `POST` | `/api/v1/skills/curator/release` | `Bulk return to user ownership; body is a string-id array` | +| `GET` | `/api/v1/skills/curator/snapshots` | `List recent workspace restore points` | +| `POST` | `/api/v1/skills/curator/snapshots` | `Capture a restore point; optional reason` | +| `POST` | `/api/v1/skills/curator/snapshots/{snapshotId}/restore` | `Restore the skill library to a restore point` | +| `GET` | `/api/v1/skills/routines` | `List recurring-request candidates` | +| `POST` | `/api/v1/skills/routines/mine` | `Run recurring-request mining now` | +| `POST` | `/api/v1/skills/routines/{id}/dismiss` | `Dismiss a candidate` | +| `POST` | `/api/v1/skills/routines/{id}/reopen` | `Reopen a candidate` | +| `POST` | `/api/v1/skills/routines/{id}/promote` | `Promote now, bypassing frequency gates` | | `GET` | `/api/v1/skills/enabled` | `List Enabled` | | `POST` | `/api/v1/skills/install/cancel/{taskId}` | `Cancel` | | `GET` | `/api/v1/skills/install/hub/search` | `Search Hub` | diff --git a/mateclaw-server/src/main/resources/docs/en/channels.md b/mateclaw-server/src/main/resources/docs/en/channels.md index 75d2c40c..de485d82 100644 --- a/mateclaw-server/src/main/resources/docs/en/channels.md +++ b/mateclaw-server/src/main/resources/docs/en/channels.md @@ -697,6 +697,20 @@ The worst part of long tasks in IM is the "message dropped into a void" feeling. --- +## Proactive push and targeted Cron delivery (2.1.0+) + +An employee can proactively notify an IM conversation when the task explicitly asks for it: + +1. call `list_channel_sessions` to list recent pushable conversations in the current workspace; +2. select the exact returned `conversation_id`; +3. call `send_channel_message` for a one-way text/Markdown notification. + +The adapters that currently implement proactive send are QQ, Telegram, WeChat, Slack, Discord, Feishu, DingTalk, and WeCom. The bot must first have received at least one message in that conversation so a verified platform delivery handle exists, and the channel must be running. Guessed ids and cross-workspace targets are rejected; messages are capped at 4096 characters. Ordinary replies still use the current conversation. + +Cron edits now retain both delivery channel and target, so changing a schedule or prompt cannot silently lose the destination. This fits scheduled reports, alerts, and asynchronous completion notifications. + +--- + ## Next - [Chat & Messaging](./chat) — message flow, segments, streaming events diff --git a/mateclaw-server/src/main/resources/docs/en/chat.md b/mateclaw-server/src/main/resources/docs/en/chat.md index 8022ef87..2ded2226 100644 --- a/mateclaw-server/src/main/resources/docs/en/chat.md +++ b/mateclaw-server/src/main/resources/docs/en/chat.md @@ -386,6 +386,25 @@ curl -X DELETE http://localhost:18088/api/v1/conversations/conv-abc123 \ --- +## Thinking visibility and linear trajectories (2.1.0+) + +2.1.0 turns thinking from one ambiguous block into segments ordered by execution: + +- inline `` content is extracted live and kept separate from the final answer; +- each ReAct iteration stays where it occurred, so tool calls and observations do not drift into the next round; +- wall-clock start/end times produce real duration and phase feedback; +- Workspace admins use “Show thinking” to control rendering and “Show all iterations” to switch between every round and only the answer-producing round; +- `mate.agent.reasoning.retention=all|terminal` controls server-side persistence; +- a conversation owner can request `GET /api/v1/conversations/{conversationId}/trajectory` for a plain-text export of user input, reasoning, tool calls, observations, and the final answer in execution order. Durations come from segment bounds and appear in the UI; the current text export does not include them. + +Provisional narration before a tool call becomes `superseded` when real output arrives. The current chat UI renders it inline, while trajectory output preserves it with `content superseded="true"`. Intermediate Team Run announcements fold into the run card instead of becoming repeated final replies. + +### Batch conversation deletion + +Sessions can batch-delete up to 200 selected conversations. The server deduplicates ids, checks ownership per item, and deletes only conversations the current user may operate. `team_worker` conversations stay out of the normal sidebar, so they do not appear in sidebar batch selection. + +--- + ## Next - [Agents](./agents) — what's actually doing the thinking diff --git a/mateclaw-server/src/main/resources/docs/en/config.md b/mateclaw-server/src/main/resources/docs/en/config.md index 067d622c..96118286 100644 --- a/mateclaw-server/src/main/resources/docs/en/config.md +++ b/mateclaw-server/src/main/resources/docs/en/config.md @@ -14,8 +14,10 @@ Deep-dive topics have their own pages — Tool Guard rules in [Security & Approv |---------|----------|--------------| | `default` | H2 file at `./data/mateclaw` | No action needed | | `mysql` | MySQL 8.0+ | `spring.profiles.active=mysql` or `SPRING_PROFILES_ACTIVE=mysql` | +| `postgres` | PostgreSQL 16+ | `SPRING_PROFILES_ACTIVE=postgres` | +| `kingbase` | KingbaseES | `SPRING_PROFILES_ACTIVE=kingbase` (opt-in driver required) | -Docker deployments activate `mysql` automatically. Desktop builds use `default`. +The public Docker Compose stack activates `postgres`. Desktop builds use `default`; the `mysql` profile remains supported for existing or self-managed deployments. --- @@ -44,7 +46,7 @@ spring: enabled: true # Available at /h2-console (disable in production) ``` -### Database — MySQL (production) +### Database — MySQL (supported self-managed deployment) ```yaml spring: @@ -53,7 +55,7 @@ spring: datasource: url: jdbc:mysql://localhost:3306/mateclaw?useSSL=false&serverTimezone=UTC username: root - password: ${MYSQL_ROOT_PASSWORD} + password: ${DB_PASSWORD} driver-class-name: com.mysql.cj.jdbc.Driver ``` @@ -63,7 +65,7 @@ spring: **Model configuration is 100% UI-driven.** Don't put `spring.ai.*` blocks in `application.yml` — every provider, key, and model config lives in `Settings → Models`, backed by the `mate_model_provider` and `mate_model_config` tables. ::: -**LLM API keys are not read from environment variables** — `DASHSCOPE_API_KEY` / `OPENAI_API_KEY` / etc. have no effect. A fresh install starts with no providers configured; log in and add your first one under `Settings → Models → Add Provider`. Full reference in [Models](./models). +**Provider, key, and model rows in the database are the primary configuration.** On a fresh install, log in and add the first provider under `Settings → Models → Add Provider`. `DASHSCOPE_API_KEY` remains a compatibility fallback for DashScope auto-configuration, but it does not replace the provider row; do not assume equivalent environment variables are read for other providers. Full reference in [Models](./models). ### Virtual threads (JDK 21) @@ -215,8 +217,8 @@ Details in [Multimodal](./multimodal). ## Environment variables -::: warning LLM keys are not read from env -DashScope / OpenAI / Anthropic / DeepSeek / Kimi and other provider API keys are **not configured via environment variables**. The container starts with zero LLM keys; after login, add your first provider under `Settings → Models → Add Provider`. +::: warning Manage LLM keys in the console +Provider, key, and model rows in `Settings → Models` are primary. `DASHSCOPE_API_KEY` remains only as a compatibility fallback for DashScope auto-configuration; do not assume equivalent environment variables are read for other providers. ::: | Variable | Required | Purpose | @@ -225,8 +227,10 @@ DashScope / OpenAI / Anthropic / DeepSeek / Kimi and other provider API keys are | `TAVILY_API_KEY` | — | Tavily search key (same as above) | | `JWT_SECRET` | — | JWT signing secret (recommended in production) | | `MATECLAW_CORS_ALLOWED_ORIGINS` | — | CORS allowlist (recommended in production) | -| `DB_PASSWORD` / `DB_ROOT_PASSWORD` | Docker | MySQL app user / root password | -| `SPRING_PROFILES_ACTIVE` | — | Set to `mysql` for production | +| `DB_PASSWORD` / `DB_ADMIN_PASSWORD` | Docker | PostgreSQL application / bootstrap-admin passwords (must differ) | +| `DB_USERNAME` / `DB_ADMIN_USERNAME` | — | PostgreSQL application / bootstrap-admin usernames | +| `DB_HOST` / `DB_PORT` / `DB_NAME` | — | Database address, port, and name | +| `SPRING_PROFILES_ACTIVE` | — | Docker Compose sets `postgres`; self-managed deployments may use `mysql` / `kingbase` | ### Setting them @@ -247,7 +251,7 @@ $env:JWT_SECRET = "your-production-secret-at-least-32-chars" ```properties DB_PASSWORD=secure-password-here -DB_ROOT_PASSWORD=different-secure-password-here +DB_ADMIN_PASSWORD=different-secure-password-here JWT_SECRET=your-production-secret-at-least-32-chars ``` @@ -290,7 +294,7 @@ CREATE DATABASE mateclaw CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ```bash export SPRING_PROFILES_ACTIVE=mysql -export MYSQL_ROOT_PASSWORD=your-password +export DB_PASSWORD=your-password mvn spring-boot:run ``` diff --git a/mateclaw-server/src/main/resources/docs/en/console.md b/mateclaw-server/src/main/resources/docs/en/console.md index dbf072af..07d21ed0 100644 --- a/mateclaw-server/src/main/resources/docs/en/console.md +++ b/mateclaw-server/src/main/resources/docs/en/console.md @@ -554,10 +554,10 @@ Unmatched paths redirect to `/chat`. ```bash cd mateclaw-ui -pnpm install -pnpm dev # Port 5173, proxies /api to :18088 -pnpm build # vue-tsc + vite build into ../mateclaw-server/.../static -pnpm lint # ESLint +npm install +npm run dev # Port 5173, proxies /api to :18088 +npm run build # vue-tsc + vite build into ../mateclaw-server/.../static +npm run lint # ESLint ``` Build artifacts embed in the Spring Boot JAR. diff --git a/mateclaw-server/src/main/resources/docs/en/contributing.md b/mateclaw-server/src/main/resources/docs/en/contributing.md index d2c29d61..71a115ff 100644 --- a/mateclaw-server/src/main/resources/docs/en/contributing.md +++ b/mateclaw-server/src/main/resources/docs/en/contributing.md @@ -32,8 +32,8 @@ Model configuration is **UI-driven** — no need to set `DASHSCOPE_API_KEY` as a ```bash cd mateclaw-ui -pnpm install -pnpm dev +npm install +npm run dev ``` Frontend on port 5173, proxies `/api` to the backend. @@ -252,14 +252,14 @@ mvn test -Dtest=StateGraphReActAgentTest#testChat # Single method ```bash cd mateclaw-ui -pnpm build # vue-tsc type check + vite build -pnpm lint # ESLint with auto-fix +npm run build # vue-tsc type check + vite build +npm run lint # ESLint with auto-fix ``` ### Manual test checklist - [ ] Backend starts without errors -- [ ] Frontend builds without type errors (`pnpm build`) +- [ ] Frontend builds without type errors (`npm run build`) - [ ] Login works with default credentials - [ ] Model configured via UI - [ ] Chat streams a response back @@ -277,7 +277,7 @@ The docs live in `docs/`. Pick the relevant page and update both `docs/en/` and ```bash cd docs -pnpm build +npm run build ``` Build must succeed with zero errors before you open the PR. diff --git a/mateclaw-server/src/main/resources/docs/en/faq.md b/mateclaw-server/src/main/resources/docs/en/faq.md index 929d3c0d..3b77634b 100644 --- a/mateclaw-server/src/main/resources/docs/en/faq.md +++ b/mateclaw-server/src/main/resources/docs/en/faq.md @@ -288,7 +288,7 @@ Configure `http_proxy` in the channel config: cp ./data/mateclaw.mv.db ./backup/mateclaw-$(date +%Y%m%d).mv.db ``` -**MySQL (production):** +**MySQL (supported self-managed deployment):** ```bash mysqldump -u root -p mateclaw > mateclaw-backup-$(date +%Y%m%d).sql @@ -297,7 +297,7 @@ mysqldump -u root -p mateclaw > mateclaw-backup-$(date +%Y%m%d).sql **Docker:** ```bash -docker exec mateclaw-mysql mysqldump -u root -p${MYSQL_ROOT_PASSWORD} mateclaw > backup.sql +docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > backup.sql ``` **Desktop** data lives in the per-user directory: @@ -332,19 +332,19 @@ Try launching from a terminal. On Windows, right-click → Unblock. On macOS, al ```bash docker compose logs mateclaw-server -docker compose logs mateclaw-mysql +docker compose logs postgres ``` Common: -- MySQL not ready yet -- Port conflicts (18080, 3306) -- Missing `.env` — copy from `.env.example` +- PostgreSQL not ready yet +- Public port 18080 is already in use +- Missing `.env`, `DB_PASSWORD`, or `DB_ADMIN_PASSWORD` ### How do I access the database in Docker? ```bash -docker exec -it mateclaw-mysql mysql -u root -p mateclaw +docker compose exec postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' ``` --- @@ -397,7 +397,7 @@ curl -N -X POST 'http://localhost:18088/api/v1/chat/stream' \ ```bash cd mateclaw-ui -pnpm build +npm run build ls ../mateclaw-server/src/main/resources/static/ # Should contain index.html and asset files ``` diff --git a/mateclaw-server/src/main/resources/docs/en/index.md b/mateclaw-server/src/main/resources/docs/en/index.md index 8e82d200..5035c29a 100644 --- a/mateclaw-server/src/main/resources/docs/en/index.md +++ b/mateclaw-server/src/main/resources/docs/en/index.md @@ -4,7 +4,7 @@ layout: home hero: name: MateClaw text: The personal AI your IT department can actually sign off on. - tagline: Other personal AI agents are built for one person. MateClaw is built for a team — multi-user workspaces, approval-gated sensitive actions, full audit trail, production-grade health monitoring. One JAR on your own machine. Zero data egress. + tagline: Other personal AI agents are built for one person. MateClaw is built for a team — multi-user workspaces, approval-gated sensitive actions, full audit trail, production-grade health monitoring. One self-hosted JAR; you control persisted data and outbound integration boundaries. image: src: /logo.png alt: MateClaw @@ -22,10 +22,10 @@ hero: 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. + 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 — six built-in 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. + details: One team request becomes one Team Run — objective, task DAG, worker execution, final synthesis, and deliverables stay together. Chat delivers outcomes, Agents observes live work, and Teams governs history and approvals. In 2.1.0, one round of collaboration is one complete work record. - 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/intro.md b/mateclaw-server/src/main/resources/docs/en/intro.md index a4c32838..a1cb7fb1 100644 --- a/mateclaw-server/src/main/resources/docs/en/intro.md +++ b/mateclaw-server/src/main/resources/docs/en/intro.md @@ -1,6 +1,6 @@ --- title: MateClaw Introduction — Self-hosted Multi-Agent AI Operating System -description: MateClaw is an open-source multi-agent AI OS built on Spring AI Alibaba. ReAct + Plan-and-Execute engines, LLM Wiki knowledge base, 4-layer memory lifecycle, MCP tool protocol, 8-channel integration. One JAR, zero data egress. +description: MateClaw is an open-source multi-agent AI OS built on Spring AI Alibaba. ReAct + Plan-and-Execute engines, LLM Wiki knowledge base, 4-layer memory lifecycle, MCP tool protocol, 8-channel integration. One self-hosted JAR with operator-controlled data and outbound integrations. head: - - meta - name: keywords @@ -11,7 +11,7 @@ head: **Your multi-agent AI. On your hardware. Under your rules.** -MateClaw is a full AI operating system you deploy yourself. One JAR. One login. Your data never leaves the room. +MateClaw is a full AI operating system you deploy yourself. One JAR. One login. You control persisted data and outbound integrations. **Three things it does that other AI products can't:** @@ -55,13 +55,13 @@ MateClaw fights a different fight. It's **all of it, under one roof, on hardware Running MateClaw on your own hardware is not a compliance checkbox. It changes what the product **is**. -**Your data stops paying rent.** Logs, conversations, documents, memory — none of it trains anyone else's model. None of it waits in a vendor's queue. None of it leaves your machines unless you point a channel at one. +**You control the data and egress boundary.** Conversations, logs, documents, and memory persist in your deployment. Only task content needed by cloud models, IM channels, MCP servers, or other tool services is sent to integrations you explicitly configure. For fully local processing, combine local models and tools and leave external integrations disabled. **You own the roadmap.** Don't like how the memory consolidator works? Change it. Need a tool your vendor won't build? Add it. MateClaw is Apache 2.0 — not source-available, not "open core", not waiting on a quarterly product review. **You pick the economics.** Start on DashScope. Swap to Ollama when your local GPU arrives. Put one agent on OpenAI and keep the rest cheap. Agent config and tool graphs don't care what's under the model interface. -**Your deployment surface is real.** One JAR. One Spring Boot process. No Python runtime chain. No Node dependency hell. The desktop app bundles everything. The Docker compose file is eighteen lines. +**Your deployment surface is real.** One JAR. One Spring Boot process. Running the service requires no separate Python or Node installation. The desktop app bundles its JRE, and one Docker Compose command starts PostgreSQL, SearXNG, and the server. --- @@ -71,7 +71,7 @@ Running MateClaw on your own hardware is not a compliance checkbox. It changes w - **Frontend** — Vue 3 + TypeScript. Pinia for state, Element Plus + Tailwind for UI, full dark mode. Built into the backend JAR's `static/` so one process serves both. - **Desktop** — Electron with bundled JRE 21 and the packaged server JAR. Launches, initializes, and your users never know Java is underneath. - **Channels** — Each channel is a `ChannelAdapter` SPI implementation. Web streams over SSE. IM channels run on their platform's long-connection or webhook mode. -- **Storage** — H2 file DB for development, MySQL 8 for production. Flyway manages schema migrations with dialect-specific scripts for each. +- **Storage** — H2 file DB for development and desktop; PostgreSQL 16 in the public Docker stack; a supported MySQL 8 profile; and an opt-in KingbaseES driver. Flyway manages schema migrations per database dialect. --- diff --git a/mateclaw-server/src/main/resources/docs/en/models.md b/mateclaw-server/src/main/resources/docs/en/models.md index f815614b..414bcabd 100644 --- a/mateclaw-server/src/main/resources/docs/en/models.md +++ b/mateclaw-server/src/main/resources/docs/en/models.md @@ -508,6 +508,19 @@ If you're on DashScope, here's the rough shape of the lineup: --- +## Per-model context windows (2.1.0+) + +MateClaw no longer treats every model as a global 128K window. Runtime resolution follows **operator override → live local-model probe or provider limit-error cache → built-in model catalog → the existing global fallback**. To avoid I/O, model-list rendering shows only override or catalog values; unknown models still use the caller's global default. The result budgets system prompts, memory, Wiki context, history, and tool schemas. + +- known models, including GLM-5V-Turbo and Kimi coding aliases, use catalogued windows; +- custom/private models can declare an accurate maximum input-token count in model management; +- the API is `PUT /api/v1/models/{providerId}/models/context-window` with `modelId` and `maxInputTokens`; null or non-positive clears the override; +- workspace members reading provider binding choices receive only id/display name, never keys or connection settings. + +The OpenAI-compatible path also preserves `integer` / `number` in tool JSON Schemas. Only non-reserved top-level `generateKwargs` entries pass through to the request body; temperature, token limits, `topP`, `reasoningEffort`, search, headers, and path keys use one consistent reserved-key reader. Unknown nested `chatOptions` keys are not forwarded, and `reasoningEffort` is sent only to explicitly supported model families. + +--- + ## Next - [Configuration](./config) — full config reference diff --git a/mateclaw-server/src/main/resources/docs/en/quickstart.md b/mateclaw-server/src/main/resources/docs/en/quickstart.md index d5924f09..44a33410 100644 --- a/mateclaw-server/src/main/resources/docs/en/quickstart.md +++ b/mateclaw-server/src/main/resources/docs/en/quickstart.md @@ -78,7 +78,7 @@ First run should Just Work. If it didn't: ## Other ways to run MateClaw - **Docker** — `cp .env.example .env`, set the passwords, then `docker compose up -d --build`. Full prerequisites, Maven mirror selection (China vs US), browser-tool self-check, and upgrade flow live in [Docker Deployment](./docker-deploy). -- **From source** — `mvn spring-boot:run` in `mateclaw-server/` and `pnpm dev` in `mateclaw-ui/`. See [Contributing](./contributing). +- **From source** — `mvn spring-boot:run` in `mateclaw-server/` and `npm run dev` in `mateclaw-ui/`. See [Contributing](./contributing). - **Desktop internals** — packaging, code signing, auto-update. See [Desktop App](./desktop). --- diff --git a/mateclaw-server/src/main/resources/docs/en/releases.md b/mateclaw-server/src/main/resources/docs/en/releases.md index 4f107648..4400d587 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.1.0](./releases/2.1.0) | 2026-08-15 | **Unified Team Runs** — one request, task DAG, worker execution, final synthesis, and deliverables share a `runId`; Chat delivery / Agents observation / Teams governance consume one projection, while worker conversations stay out of the normal sidebar · **closed skill-evolution loop** (cross-session recurring-request mining · reflection · constrained auto-binding · curator governance handover · origin policy · snapshots and restore points, workspace-scoped and conservative by default) · **replayable reasoning** (live `` extraction · UI wall-clock duration · all/terminal display controls · plain-text trajectory export) · proactive channel push + targeted Cron delivery · context-window override/probe/catalog budgeting · progressive tool bridge + action completion policy · hardened browser refs/navigation/waits · WebChat/SSE/LLM stream cleanup and timeouts · Feishu execution progress · Qwen3-ASR HTTP · batch session deletion · date-partitioned files · 64-bit id and numeric tool-schema precision fixes | | [v2.0.0](./releases/2.0.0) | 2026-07-31 | **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 | diff --git a/mateclaw-server/src/main/resources/docs/en/roadmap.md b/mateclaw-server/src/main/resources/docs/en/roadmap.md index 6c5e090c..11e81415 100644 --- a/mateclaw-server/src/main/resources/docs/en/roadmap.md +++ b/mateclaw-server/src/main/resources/docs/en/roadmap.md @@ -130,7 +130,7 @@ 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) +### v2.0 — It leads a team ✅ Released (2026-07-31) From "one person who gets things done" to "a team that collaborates" — **Agent Teams** become a standing roster around a shared task board. @@ -143,13 +143,26 @@ From "one person who gets things done" to "a team that collaborates" — **Agent Full story: [v2.0.0 release notes](./releases/2.0.0.md); user guide: [Agent Teams](./teams). +### v2.1 — It turns team work into a governable run ✅ Released (2026-08-15) + +2.0 built teams and their task board. 2.1 joins the three chains exposed by continuous use: **one identity for a team request, a replayable trajectory for execution, and provenance plus recovery for every skill improvement**. + +- **Unified Team Runs**: one `runId` links request, task DAG, worker execution, final synthesis, and deliverables; Chat delivers, Agents observes, and Teams governs the same projection +- **Outcome-first delivery**: worker conversations leave the normal sidebar, intermediate announcements fold in, and summaries, files, exceptions, and approvals lead while detail drills down progressively +- **Closed skill-evolution loop**: reflection + cross-session recurring-request mining + promotion + constrained auto-binding + curator governance handover + snapshot/restore; reflection/routine default off, curator stays preview-only before activation, and changes remain workspace-scoped and reversible +- **Replayable reasoning and execution**: every thinking round, wall-clock duration, tool/observation order, superseded narration, and linear trajectory export +- **Capabilities reach real operations**: proactive channel messages, targeted Cron delivery, model-level context windows, progressive tool bridge, and action-completion policy +- Broad hardening across browser automation, WebChat/SSE, Feishu progress, Qwen3-ASR, file layout, and 64-bit id precision + +Full story: [v2.1.0 release notes](./releases/2.1.0.md); guides: [Team Runs](./teams) and [Skills](./skills). + --- ## 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.7 made long tasks visible, and **v2.0 made teams a standing roster**. +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, v2.0 made teams a standing roster, and **v2.1 made every round deliverable, learnable, and governable**. 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. @@ -225,6 +238,7 @@ A leader on a loop, members summoned on demand — that's a **self-running digit | **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 | | **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 | +| **v2.1** | **It turns collaboration into a run** | **Unified Team Runs + closed skill evolution + replayable reasoning trajectories + proactive channel delivery** | ✅ 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 | --- @@ -237,7 +251,7 @@ We're building it because we believe one thing: **AI shouldn't be a chat box on a webpage. It should be your second brain.** -It lives in your DingTalk, your Feishu, your Telegram. It's read every document you have. It remembers what you said three months ago. It uses your company's internal tools. It consolidates memory while you sleep. It runs an entire business flow on your behalf. **Soon it will lead a standing team, stay on duty, and watch over the things you can't get to.** +It lives in your DingTalk, your Feishu, your Telegram. It's read every document you have. It remembers what you said three months ago. It uses your company's internal tools. It consolidates memory while you sleep. It runs an entire business flow on your behalf. **It can now deliver one complete round of team work and learn from it; next, that team stays on duty and watches over the things you can't get to.** Someday, you'll forget it's a program. diff --git a/mateclaw-server/src/main/resources/docs/en/security.md b/mateclaw-server/src/main/resources/docs/en/security.md index d0836eb0..16dc5df3 100644 --- a/mateclaw-server/src/main/resources/docs/en/security.md +++ b/mateclaw-server/src/main/resources/docs/en/security.md @@ -494,7 +494,7 @@ Scan reports live in `Settings → Security & Approval → Skill Scans`. | **Disable H2 console** | `spring.h2.console.enabled=false` in production | | **Firewall** | Only expose the public port | | **Rate limiting** | Configure at the reverse proxy level | -| **MySQL, not H2** | Use a dedicated MySQL 8 instance for production | +| **Production database, not H2** | Follow the public Docker stack with PostgreSQL 16, or use a dedicated MySQL 8 / KingbaseES instance | ### Nginx reverse proxy example diff --git a/mateclaw-server/src/main/resources/docs/en/skills.md b/mateclaw-server/src/main/resources/docs/en/skills.md index 41b3265c..6e663879 100644 --- a/mateclaw-server/src/main/resources/docs/en/skills.md +++ b/mateclaw-server/src/main/resources/docs/en/skills.md @@ -676,6 +676,24 @@ See [Content Studio](./content-studio) for the full pipeline, publish chain, and --- +## Closed skill-evolution loop (2.1.0+) + +2.1.0 expands LESSONS.md learning into an inspectable, reversible improvement chain: + +1. **Reflection** proposes a precise patch or new-skill candidate from a completed conversation. +2. **Routine mining** clusters recent conversations' opening user requests per employee; it does not mine a full execution trace. The default window is 30 days, with at least three occurrences across three distinct days. Once enabled, the nightly job automatically promotes qualified candidates (two per sweep by default); admins may promote early, dismiss, or reopen. +3. **Automatic binding** only handles a new skill with a source employee, and adds a row only when that employee already uses an explicit, non-empty skill allowlist. Inherit-all needs no binding, while an explicit no-skills choice is never overwritten. +4. **Curator** organizes stale, archived, and overlapping skills per workspace. It starts preview-only and mutates only after admin activation; consolidation is separately enabled, with umbrella creation and source archiving transactional. +5. **Adopt / release** transfers governance: adopt hands a user skill to autonomous curation, while release returns it to user ownership. It is not a record of which employee uses the skill. +6. **Snapshots** create a restore point before every activated mutating sweep and again before restore; five are retained per workspace by default. +7. **Origin** distinguishes built-in, user, agent, and routine, while also serving as curator policy. Manual handover intentionally changes the user / agent state. + +The secure default is **observe before allowing automatic writes**: reflection and routine mining are disabled until explicitly enabled. Reflection's `enabled` switch controls whether transcript/catalog data reaches the reviewer model, while `auto-apply` separately controls mutations; with auto-apply off nothing is written, but there is no persisted human-approval queue. Transcripts and skill bodies are treated as untrusted data; automatic writes allow only create or a unique-context patch. Full replacement, secret exfiltration, approval bypasses, and cross-workspace reads/writes fail closed. + +`Settings → Skill Curator` shows workspace state, routine candidates, recent reports, origin, managed/unmanaged skills, and restore points. Curator, routine, snapshot, adopt, and release operations all require the current workspace context. + +--- + ## Next - [Tools](./tools) — tools that skills can use diff --git a/mateclaw-server/src/main/resources/docs/en/teams.md b/mateclaw-server/src/main/resources/docs/en/teams.md index 0934154b..d1c1f63a 100644 --- a/mateclaw-server/src/main/resources/docs/en/teams.md +++ b/mateclaw-server/src/main/resources/docs/en/teams.md @@ -1,13 +1,13 @@ --- -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. +title: Team Runs — from one team request to a complete, deliverable execution +description: A MateClaw Team Run links the lead, task DAG, worker executions, final synthesis, and deliverables under one runId and one shared view across Chat, Agents, and Teams. head: - - meta - name: keywords content: agent teams,task board,kanban,multi-agent collaboration,dispatch,deliverables,MateClaw --- -# Agent Teams (2.0.0+) +# Team Runs and Agent Teams (2.1.0+) > **Before: one employee with sub-tasks. Now: a team around a shared task board.** @@ -15,6 +15,32 @@ Sub-agent delegation (`delegateToAgent`) solves "one person temporarily calls a 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. +2.1.0 adds the first-class **Team Run** above individual tasks: one user request maps to one run, and one `runId` links the objective, task DAG, worker conversations, events, final synthesis, and deliverables. Instead of a sidebar full of “subtask” conversations, you get one outcome-first work record with progressive drill-down. + +## The unified Team Run experience in 2.1.0 + +| Surface | Responsibility | Default view | +|---------|----------------|--------------| +| **Chat** | Delivery | One stable run card with shared status/progress, final summary, deliverables, failures or approvals; task detail expands on demand | +| **Agents · Live** | Live observation | Workers sharing a `runId` are grouped with task, phase, tool, duration, and exception state; ordinary runs remain independent | +| **Teams** | History and governance | Run history and detail, task evidence, approvals, cancellation, and worker records instead of a flat wall of historical tasks | + +The server owns the Team Run projection and state machine: + +```text +planning → running → awaiting_review → finalizing → completed + ↘ partial / failed +planning / running / awaiting_review → cancelled +``` + +- **One identity per job**: events, routes, logs, tasks, and final messages carry `runId`. +- **Outcome first**: intermediate task settlement updates progress instead of manufacturing one user-facing final answer per task. +- **Worker governance**: `team_worker` conversations stay out of the normal sidebar; deep links open a read-only execution record with a path back to the Team Run. +- **Refresh-safe**: every surface consumes `TeamRunView`, so title, progress, status, summary, and files cannot drift through client-side inference. +- **Historical compatibility**: 2.0 tasks without `runId` remain readable but are never guessed into an incorrect aggregate. + +The run protocol is `start_run → create* → seal_run`: the lead creates a run, creates tasks explicitly under it, and seals it before dispatch. The originating message participates in idempotency, preventing reconnects or duplicate submissions from creating a second copy. + --- ## Core concepts @@ -122,6 +148,10 @@ The admin API lives under `/api/v1/teams`: | Endpoint | Description | |------|------| +| `GET /api/v1/team-runs/{runId}` | Read the complete run projection | +| `GET /api/v1/teams/{teamId}/runs` · `GET …/runs/page` | List / cursor-page team run history | +| `GET /api/v1/conversations/{conversationId}/team-runs` · `GET …/team-runs/page` | List / cursor-page runs in a parent conversation | +| `POST /api/v1/team-runs/{runId}/cancel` | Cancel a run and its non-terminal tasks | | `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 | @@ -135,7 +165,7 @@ The admin API lives under `/api/v1/teams`: 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`. +The original five team tables are joined by `mate_team_run`; `mate_team_task.run_id` and worker-conversation indexes connect tasks, runs, and execution records. Snowflake ids cross the JSON boundary as strings. --- diff --git a/mateclaw-server/src/main/resources/docs/en/tools.md b/mateclaw-server/src/main/resources/docs/en/tools.md index bbdf89be..ff9730b3 100644 --- a/mateclaw-server/src/main/resources/docs/en/tools.md +++ b/mateclaw-server/src/main/resources/docs/en/tools.md @@ -387,6 +387,18 @@ Capability already exists as an MCP server? Just add the server configuration. S --- +## 2.1.0: progressive tool bridge and action completion + +With a large tool catalog, MateClaw exposes a lightweight directory first and expands concrete schemas only when the task needs them. The progressive bridge reduces context pressure; normalized, enabled tool names are cached so long loops do not repeatedly scan the MCP hot path. + +Action requests now carry a completion policy: when the user explicitly asks to send, create, delete, query an external system, or operate a browser, the runtime retries once if its ledger has no successful substantive tool call. A second text-only attempt ends as `action_unverified`; a substantive attempt that failed ends as `action_failed`, rather than claiming completion. This proves that a substantive call succeeded, not semantic equivalence between its result and the user's goal. Read-only explanations and answers that need no tool are unaffected. + +`browser_use` hardens ref lifetime, navigation safety, session gates, wait conditions, and snapshots. Page changes explicitly invalidate old refs, and navigation/wait outcomes are diagnosable instead of silently clicking a stale element or crossing browser sessions. + +The proactive `list_channel_sessions` / `send_channel_message` tools push only to verified conversations in the current workspace; see [Channels](./channels). + +--- + ## Next - [Skills](./skills) — higher-level capabilities built on tools diff --git a/mateclaw-server/src/main/resources/docs/zh/agents.md b/mateclaw-server/src/main/resources/docs/zh/agents.md index eefe97c8..21168222 100644 --- a/mateclaw-server/src/main/resources/docs/zh/agents.md +++ b/mateclaw-server/src/main/resources/docs/zh/agents.md @@ -38,31 +38,26 @@ head: | **最大迭代次数** | 强制收敛前允许走多少轮推理循环 | | **启用开关** | 关掉它 | -注意一个**没有**的东西：模型。整个 MateClaw 部署里只有**一个全局默认模型**（在 `设置 → 模型` 里设置），所有 Agent 在运行时用的都是它。Agent 行上那个 `model_name` 字段是历史遗留——**被忽略**。这是刻意的：换模型是整个部署一次点击的事，不是三十次。 +模型按 **会话固定模型 → Agent 模型覆盖 → 全局默认模型** 的优先级解析。会话可以临时固定一个已启用的供应商 / 模型；Agent 也可以选择自己的主模型，留空才继承全局默认。若固定项已被禁用或删除，运行时会回退到 Agent 覆盖或全局默认，而不是让会话直接失败。每个 Agent 还可维护按供应商 + 模型排列的故障转移偏好链。 --- ## 模板：从一个已经会工作的同事开始 -你不是从一张白纸开始。`数字员工 → 新建` 打开一个模板选择器。里面有两层： +你不必从一张白纸开始。`数字员工 → 新建` 会打开模板选择器，列出服务端 `classpath:templates/*.json` 中的模板；也可以跳过模板，直接进入空白表单。 -### 5 个职业模板（推荐） +### 6 个内置模板（推荐） 每一个都自带角色、目标、背景故事、合适的工具集、像素艺术头像、专属配色——**打开就能用**： -- **产品研究员**——竞品调研、市场动态追踪、用户访谈整理 -- **客户支持**——接住客户问的事、查知识库、把不能解决的升级出去 -- **知识管理员**——把零散材料整理进 LLM Wiki、维护双向链接、定期归纳 +- **通用助手**——搜索、写作、分析等日常任务 +- **产品助理**——澄清用户、场景与需求，整理产品判断 +- **研究分析师**——拆解复杂研究任务，结合网络搜索与 Wiki +- **客服助理**——先共情，再查知识并解决或升级问题 - **数据分析师**——查数据源、跑 SQL、出图表、写结论 -- **行政助理**——日程、邮件草稿、跨工具协调 +- **代码审查员**——阅读代码、发现问题并给出改进建议 -### 通用模板（白纸或半成品） - -- **通用助手**——默认的聊天员工 -- **研究 / 代码 / 写作 / 知识策展 / 数据分析**——按用途分类的半成品 -- **自定义**——彻底白纸一张，知道自己要什么就选这个 - -选一个，给它起名字、调一下角色和目标，保存。**一分钟以内就有一个能上岗的同事。** 创建之后每一项都能改。 +选择模板会直接创建对应 Agent；跳过模板则进入可完整编辑的自定义表单。创建之后，名称、角色、目标、模型、技能、工具和知识库范围仍可继续调整。 --- @@ -235,7 +230,7 @@ REST：`GET /api/v1/plans?limit=N`（跨员工最近 N 条）、`GET /api/v1/pla `数字员工 → 新建`： -1. 选一个模板（5 个职业模板之一，或通用模板，或 Custom） +1. 选一个内置模板，或从自定义配置开始 2. 起名字，挑头像（像素艺术风格的库可选，或自己上传） 3. 写**角色 (Role)**——一句话；**目标 (Goal)**——一句话；**背景故事 (Backstory)**——几句话 4. 写一句**员工卡片标语 (Tagline)**——卡片上展示的"自我介绍" diff --git a/mateclaw-server/src/main/resources/docs/zh/api.md b/mateclaw-server/src/main/resources/docs/zh/api.md index ac313a2b..3383becf 100644 --- a/mateclaw-server/src/main/resources/docs/zh/api.md +++ b/mateclaw-server/src/main/resources/docs/zh/api.md @@ -337,7 +337,7 @@ curl -X POST http://localhost:18088/api/v1/agents \ `MessageVO` 关键字段：`id`、`role`、`content`、`toolName`、`status`、`metadata`（对象，含 toolCalls 等）、`promptTokens` / `completionTokens`、`runtimeModel` / `runtimeProvider`、`contentParts`、`createTime`。 -**会话级操作**：`PUT .../title`（重命名）、`PUT .../pin`（置顶 `{pinned:bool}`）、`PUT .../model`（切换模型 `{modelProvider, modelName}`）、`DELETE .../messages`（清空消息保留会话）、`DELETE .../{conversationId}`（删除会话）、`POST /batch-delete`（`{conversationIds: [...]}`）、`GET .../status`（查流状态 `{streamStatus}`）。 +**会话级操作**：`PUT .../title`（重命名）、`PUT .../pin`（置顶 `{pinned:bool}`）、`PUT .../model`（切换模型 `{modelProvider, modelName}`）、`DELETE .../messages`（清空消息保留会话）、`DELETE .../{conversationId}`（删除会话）、`POST /batch-delete`（`{conversationIds: [...]}`，去重后最多 200 个）、`GET .../status`（查流状态 `{streamStatus}`）、`GET .../trajectory`（按 segment 发射顺序导出纯文本轨迹）。 > 所有操作都先校验 `isConversationOwner(conversationId, username)`，非归属者返回 403。 @@ -350,6 +350,7 @@ curl -X POST http://localhost:18088/api/v1/agents \ - `GET /api/v1/models/default` — 全局默认模型（`R`）。 - `GET /api/v1/models/active` — 当前激活模型 `{activeLlm: {provider, modelName}}`。 - `PUT /api/v1/models/active` — 设置激活模型。 +- `PUT /api/v1/models/{providerId}/models/context-window` — global admin 设置某个 `modelId` 的 `maxInputTokens`；传 `null` 或非正数清除覆盖。 ### 审计事件（分页示范） @@ -440,6 +441,20 @@ curl -X PUT "http://localhost:18088/api/v1/auth/users/1/password?oldPassword=adm | `PUT` | `/api/v1/conversations/{conversationId}/pin` | `置顶或取消置顶会话` | | `GET` | `/api/v1/conversations/{conversationId}/status` | `获取会话流状态` | | `PUT` | `/api/v1/conversations/{conversationId}/title` | `重命名会话` | +| `GET` | `/api/v1/conversations/{conversationId}/trajectory` | `导出会话轨迹（纯文本，会话所有者）` | + +### Team Runs（2.1.0+） + +| 方法 | 路径 | 用途 / handler | +|---|---|---| +| `GET` | `/api/v1/team-runs/{runId}` | `读取一个 Team Run（viewer+）` | +| `POST` | `/api/v1/team-runs/{runId}/cancel` | `取消整轮运行，可选 {reason}（admin）` | +| `GET` | `/api/v1/teams/{teamId}/runs` | `列出团队运行，可选 activeOnly（viewer+）` | +| `GET` | `/api/v1/teams/{teamId}/runs/page` | `按 cursor / limit 分页列出团队运行，可选 activeOnly（viewer+）` | +| `GET` | `/api/v1/conversations/{conversationId}/team-runs` | `列出 Lead 会话关联运行（viewer+）` | +| `GET` | `/api/v1/conversations/{conversationId}/team-runs/page` | `按 cursor / limit 分页列出会话运行（viewer+）` | + +所有接口都按当前工作空间校验（`X-Workspace-Id` 省略时沿用默认工作空间 1）；Snowflake id 在前端/API 消费侧应按字符串处理。 ### Agent @@ -628,6 +643,7 @@ curl -X PUT "http://localhost:18088/api/v1/auth/users/1/password?oldPassword=adm | `POST` | `/api/v1/models/{providerId}/disable` | `禁用 Provider（如其下模型为当前默认会自动切换）` | | `POST` | `/api/v1/models/{providerId}/discover` | `发现远端模型` | | `POST` | `/api/v1/models/{providerId}/discover/apply` | `批量添加发现的模型` | +| `PUT` | `/api/v1/models/{providerId}/models/context-window` | `设置/清除单模型最大输入 token（global admin）` | | `POST` | `/api/v1/models/{providerId}/enable` | `启用 Provider` | | `DELETE` | `/api/v1/models/{providerId}/models` | `从 Provider 删除模型` | | `POST` | `/api/v1/models/{providerId}/models` | `向 Provider 添加模型` | @@ -711,6 +727,19 @@ curl -X PUT "http://localhost:18088/api/v1/auth/users/1/password?oldPassword=adm | `GET` | `/api/v1/skills/curator/reports/{runId}` | `读取某次 curator 运行报告` | | `POST` | `/api/v1/skills/curator/resume` | `恢复 curator 定时扫描` | | `GET` | `/api/v1/skills/curator/status` | `curator 控制面状态` | +| `POST` | `/api/v1/skills/curator/consolidate` | `开启/关闭 curator 合并去重 pass` | +| `GET` | `/api/v1/skills/curator/managed` | `列出已纳入自治治理的技能` | +| `GET` | `/api/v1/skills/curator/unmanaged` | `列出未纳入自治治理的技能` | +| `POST` | `/api/v1/skills/curator/adopt` | `批量把技能移交自治治理；请求体为字符串 id 数组` | +| `POST` | `/api/v1/skills/curator/release` | `批量把技能归还用户所有；请求体为字符串 id 数组` | +| `GET` | `/api/v1/skills/curator/snapshots` | `列出当前工作空间最近的还原点` | +| `POST` | `/api/v1/skills/curator/snapshots` | `手动捕获还原点，可选 reason` | +| `POST` | `/api/v1/skills/curator/snapshots/{snapshotId}/restore` | `回滚技能库到还原点` | +| `GET` | `/api/v1/skills/routines` | `列出高频请求候选` | +| `POST` | `/api/v1/skills/routines/mine` | `立即运行一次重复请求挖掘` | +| `POST` | `/api/v1/skills/routines/{id}/dismiss` | `忽略候选` | +| `POST` | `/api/v1/skills/routines/{id}/reopen` | `重新观察候选` | +| `POST` | `/api/v1/skills/routines/{id}/promote` | `立即晋升候选，跳过频次门槛` | | `GET` | `/api/v1/skills/enabled` | `获取已启用技能列表` | | `POST` | `/api/v1/skills/install/cancel/{taskId}` | `取消安装任务` | | `GET` | `/api/v1/skills/install/hub/search` | `搜索 ClawHub 市场` | diff --git a/mateclaw-server/src/main/resources/docs/zh/channels.md b/mateclaw-server/src/main/resources/docs/zh/channels.md index 19faa59d..dfcbcc27 100644 --- a/mateclaw-server/src/main/resources/docs/zh/channels.md +++ b/mateclaw-server/src/main/resources/docs/zh/channels.md @@ -697,6 +697,20 @@ IM 渠道（企业微信、微信、钉钉）都支持语音输入。语音识 --- +## 主动推送与 Cron 定向投递（2.1.0+） + +数字员工可以在任务明确要求通知时主动向 IM 会话推送： + +1. 调用 `list_channel_sessions`，按最近活跃时间列出当前工作空间可推送的会话； +2. 从返回值选择准确的 `conversation_id`； +3. 调用 `send_channel_message` 发送单向文本/Markdown 通知。 + +当前实现主动发送的适配器是 QQ、Telegram、微信、Slack、Discord、飞书、钉钉和企业微信。机器人必须先在该会话收到过至少一条消息，平台投递句柄才可信；渠道必须启用并支持主动发送。工具不会接受猜测的 id，跨工作空间目标会被拒绝，消息最长 4096 字符。普通回复仍走当前对话，不需要主动推送工具。 + +Cron 编辑器会持久保存 delivery channel 和 target；修改表达式或提示词后，投递位置不会丢失。适合定时报告、告警和异步任务完成通知。 + +--- + ## 下一步 - [聊天与消息](./chat)——消息流、segment、流式事件 diff --git a/mateclaw-server/src/main/resources/docs/zh/chat.md b/mateclaw-server/src/main/resources/docs/zh/chat.md index 1058fb89..e2774b41 100644 --- a/mateclaw-server/src/main/resources/docs/zh/chat.md +++ b/mateclaw-server/src/main/resources/docs/zh/chat.md @@ -386,6 +386,25 @@ curl -X DELETE http://localhost:18088/api/v1/conversations/conv-abc123 \ --- +## 思考过程与线性轨迹（2.1.0+） + +2.1.0 把思考从“一个模糊的大段”变成按执行顺序排列的 segment： + +- 模型流中的 `` 在生成时实时提取，与最终答案分开； +- ReAct 每轮推理保留在它真正发生的位置，工具调用和观察不会与下一轮错序； +- 每段记录 wall-clock 起止时间，界面显示真实耗时与阶段脉冲； +- 管理员可在系统设置中用「显示思考」控制是否渲染，用「显示全部轮次」控制显示全部还是只显示产出答案的轮次； +- `mate.agent.reasoning.retention=all|terminal` 控制服务端保存全部轮次还是最终轮次； +- 会话所有者可请求 `GET /api/v1/conversations/{conversationId}/trajectory`，把用户消息、reasoning、tool call、observation 和 final answer 导出为按执行顺序排列的纯文本。耗时来自 segment 起止时间并显示在 UI 中，当前纯文本导出不附带耗时字段。 + +工具执行前的阶段性叙述在真实结果到达后会标记为 `superseded`。当前聊天界面直接显示这些内容，trajectory 则用 `content superseded="true"` 明确标记并保留。Team Run 的中间通报会合并进运行卡片，不再重复形成多条最终答复。 + +### 会话批量删除 + +Sessions 页一次可选择最多 200 个会话批量删除。服务端会对每个 id 去重、校验所有权，并只删除当前用户有权操作的会话。`team_worker` 不进入普通侧栏，因此不会出现在侧栏批量选择中。 + +--- + ## 下一步 - [Agent 引擎](./agents)——真正在思考的是什么 diff --git a/mateclaw-server/src/main/resources/docs/zh/config.md b/mateclaw-server/src/main/resources/docs/zh/config.md index e7a43d18..11dcacc3 100644 --- a/mateclaw-server/src/main/resources/docs/zh/config.md +++ b/mateclaw-server/src/main/resources/docs/zh/config.md @@ -14,8 +14,10 @@ |---------|--------|----------| | `default` | H2 文件 `./data/mateclaw` | 不用做什么 | | `mysql` | MySQL 8.0+ | `spring.profiles.active=mysql` 或环境变量 | +| `postgres` | PostgreSQL 16+ | `SPRING_PROFILES_ACTIVE=postgres` | +| `kingbase` | KingbaseES | `SPRING_PROFILES_ACTIVE=kingbase`（需按需驱动） | -Docker 部署自动激活 `mysql`。桌面版用 `default`。 +公开 Docker Compose 自动激活 `postgres`。桌面版使用 `default`；`mysql` profile 继续支持已有或自管部署。 --- @@ -44,7 +46,7 @@ spring: enabled: true # /h2-console 可访问（生产环境关掉） ``` -### 数据库 —— MySQL（生产） +### 数据库 —— MySQL（支持的自管部署） ```yaml spring: @@ -53,7 +55,7 @@ spring: datasource: url: jdbc:mysql://localhost:3306/mateclaw?useSSL=false&serverTimezone=UTC username: root - password: ${MYSQL_ROOT_PASSWORD} + password: ${DB_PASSWORD} driver-class-name: com.mysql.cj.jdbc.Driver ``` @@ -63,7 +65,7 @@ spring: **模型配置 100% 通过 UI 管理。** 不要在 `application.yml` 里放 `spring.ai.*` 块——每个供应商、每个 key、每个模型配置都住在 `设置 → 模型` 里，底层存在 `mate_model_provider` 和 `mate_model_config` 表。 ::: -**LLM API Key 不读取环境变量**——`DASHSCOPE_API_KEY` / `OPENAI_API_KEY` 等都不再起作用。新装的实例启动时数据库里没有供应商，登录后到「设置 → 模型 → 添加供应商」加你的第一个供应商即可。完整参考在 [模型配置](./models)。 +**模型供应商、Key 与模型记录以数据库配置为准。** 新装实例登录后到「设置 → 模型 → 添加供应商」添加第一个供应商。`DASHSCOPE_API_KEY` 仍可作为 DashScope 自动配置的兼容回退，但不替代管理界面的供应商配置；不要假设其他供应商会读取同名环境变量。完整参考在 [模型配置](./models)。 ### 虚拟线程（JDK 21） @@ -215,8 +217,8 @@ mate: ## 环境变量 -::: warning LLM Key 不读环境变量 -DashScope / OpenAI / Anthropic / DeepSeek / Kimi 等供应商的 API Key **不通过环境变量配置**——容器零 Key 也能起来，登录后到「设置 → 模型 → 添加供应商」里加。 +::: warning LLM Key 以管理界面为准 +供应商、Key 和模型记录以「设置 → 模型」里的数据库配置为主。`DASHSCOPE_API_KEY` 仅保留为 DashScope 自动配置的兼容回退；不要假设其他供应商会读取同名环境变量。 ::: | 变量 | 必填 | 用途 | @@ -225,8 +227,10 @@ DashScope / OpenAI / Anthropic / DeepSeek / Kimi 等供应商的 API Key **不 | `TAVILY_API_KEY` | — | Tavily 搜索 key（同上） | | `JWT_SECRET` | — | JWT 签名密钥（生产推荐） | | `MATECLAW_CORS_ALLOWED_ORIGINS` | — | CORS 白名单（生产推荐） | -| `DB_PASSWORD` / `DB_ROOT_PASSWORD` | Docker | MySQL 业务库 / root 密码 | -| `SPRING_PROFILES_ACTIVE` | — | 生产设为 `mysql` | +| `DB_PASSWORD` / `DB_ADMIN_PASSWORD` | Docker | PostgreSQL 应用账号 / 引导管理员密码（必须不同） | +| `DB_USERNAME` / `DB_ADMIN_USERNAME` | — | PostgreSQL 应用账号 / 引导管理员账号 | +| `DB_HOST` / `DB_PORT` / `DB_NAME` | — | 数据库地址、端口与库名 | +| `SPRING_PROFILES_ACTIVE` | — | Docker Compose 自动设为 `postgres`；自管部署也可用 `mysql` / `kingbase` | ### 怎么设 @@ -247,7 +251,7 @@ $env:JWT_SECRET = "your-production-secret-at-least-32-chars" ```properties DB_PASSWORD=secure-password-here -DB_ROOT_PASSWORD=different-secure-password-here +DB_ADMIN_PASSWORD=different-secure-password-here JWT_SECRET=your-production-secret-at-least-32-chars ``` @@ -290,7 +294,7 @@ CREATE DATABASE mateclaw CHARACTER SET utf8mb4 COLLATE utf8mb4_unicode_ci; ```bash export SPRING_PROFILES_ACTIVE=mysql -export MYSQL_ROOT_PASSWORD=your-password +export DB_PASSWORD=your-password mvn spring-boot:run ``` diff --git a/mateclaw-server/src/main/resources/docs/zh/console.md b/mateclaw-server/src/main/resources/docs/zh/console.md index 0e0261f9..92dc4faf 100644 --- a/mateclaw-server/src/main/resources/docs/zh/console.md +++ b/mateclaw-server/src/main/resources/docs/zh/console.md @@ -554,10 +554,10 @@ fetch('/api/v1/chat/stream', { ```bash cd mateclaw-ui -pnpm install -pnpm dev # 5173 端口，把 /api proxy 到 18088 -pnpm build # vue-tsc + vite build，产物进 ../mateclaw-server/.../static -pnpm lint # ESLint +npm install +npm run dev # 5173 端口，把 /api proxy 到 18088 +npm run build # vue-tsc + vite build，产物进 ../mateclaw-server/.../static +npm run lint # ESLint ``` 构建产物嵌入 Spring Boot JAR。 diff --git a/mateclaw-server/src/main/resources/docs/zh/contributing.md b/mateclaw-server/src/main/resources/docs/zh/contributing.md index e5cb34a2..1dd4bae6 100644 --- a/mateclaw-server/src/main/resources/docs/zh/contributing.md +++ b/mateclaw-server/src/main/resources/docs/zh/contributing.md @@ -32,8 +32,8 @@ mvn spring-boot:run ```bash cd mateclaw-ui -pnpm install -pnpm dev +npm install +npm run dev ``` 前端在 5173 端口，把 `/api` proxy 到后端。 @@ -251,14 +251,14 @@ mvn test -Dtest=StateGraphReActAgentTest#testChat # 单个方法 ```bash cd mateclaw-ui -pnpm build # vue-tsc 类型检查 + vite build -pnpm lint # ESLint 自动修复 +npm run build # vue-tsc 类型检查 + vite build +npm run lint # ESLint 自动修复 ``` ### 手动测试清单 - [ ] 后端启动无错 -- [ ] 前端编译无类型错误（`pnpm build`） +- [ ] 前端编译无类型错误（`npm run build`） - [ ] 用默认凭证能登录 - [ ] 模型在 UI 里配好了 - [ ] 对话能流式返回 @@ -276,7 +276,7 @@ PR 改了用户面行为——新功能、重命名的端点、改过的配置 k ```bash cd docs -pnpm build +npm run build ``` **PR 开出来之前 build 必须零错误通过。** diff --git a/mateclaw-server/src/main/resources/docs/zh/faq.md b/mateclaw-server/src/main/resources/docs/zh/faq.md index 817bfbe2..7953de8e 100644 --- a/mateclaw-server/src/main/resources/docs/zh/faq.md +++ b/mateclaw-server/src/main/resources/docs/zh/faq.md @@ -288,7 +288,7 @@ UI 里用 `工具 → MCP 服务`。三种传输模式：stdio、streamable_http cp ./data/mateclaw.mv.db ./backup/mateclaw-$(date +%Y%m%d).mv.db ``` -**MySQL（生产）：** +**MySQL（受支持的自管部署）：** ```bash mysqldump -u root -p mateclaw > mateclaw-backup-$(date +%Y%m%d).sql @@ -297,7 +297,7 @@ mysqldump -u root -p mateclaw > mateclaw-backup-$(date +%Y%m%d).sql **Docker：** ```bash -docker exec mateclaw-mysql mysqldump -u root -p${MYSQL_ROOT_PASSWORD} mateclaw > backup.sql +docker compose exec -T postgres sh -c 'pg_dump -U "$POSTGRES_USER" "$POSTGRES_DB"' > backup.sql ``` **桌面端**数据在每个用户目录下： @@ -332,19 +332,19 @@ docker exec mateclaw-mysql mysqldump -u root -p${MYSQL_ROOT_PASSWORD} mateclaw > ```bash docker compose logs mateclaw-server -docker compose logs mateclaw-mysql +docker compose logs postgres ``` 常见： -- MySQL 还没就绪 -- 端口冲突（18080、3306） -- 缺 `.env`——从 `.env.example` 拷一份 +- PostgreSQL 还没就绪 +- 对外端口 18080 冲突 +- 缺 `.env` 或未填写必需的 `DB_PASSWORD` / `DB_ADMIN_PASSWORD` ### 怎么在 Docker 里访问数据库？ ```bash -docker exec -it mateclaw-mysql mysql -u root -p mateclaw +docker compose exec postgres sh -c 'psql -U "$POSTGRES_USER" -d "$POSTGRES_DB"' ``` --- @@ -397,7 +397,7 @@ curl -N -X POST 'http://localhost:18088/api/v1/chat/stream' \ ```bash cd mateclaw-ui -pnpm build +npm run build ls ../mateclaw-server/src/main/resources/static/ # 应该包含 index.html 和资源文件 ``` diff --git a/mateclaw-server/src/main/resources/docs/zh/index.md b/mateclaw-server/src/main/resources/docs/zh/index.md index 2887d5b5..cc4a9031 100644 --- a/mateclaw-server/src/main/resources/docs/zh/index.md +++ b/mateclaw-server/src/main/resources/docs/zh/index.md @@ -4,7 +4,7 @@ layout: home hero: name: MateClaw text: 公司允许部署的那一个 AI。 - tagline: 别的 AI 助手是给一个人用的。MateClaw 是给一个团队用的——多用户工作空间、敏感操作走审批、完整审计日志、生产级健康监控。一个 JAR 包跑在自己机器上，数据不出门。 + tagline: 别的 AI 助手是给一个人用的。MateClaw 是给一个团队用的——多用户工作空间、敏感操作走审批、完整审计日志、生产级健康监控。一个 JAR 包自部署，持久化数据与外发集成边界由你掌控。 image: src: /logo.png alt: MateClaw @@ -22,10 +22,10 @@ hero: features: - icon: 🧑‍💼 title: 数字员工，不是聊天机器人 - details: 你雇佣同事，不是开聊天框。每位有角色 / 目标 / 背景故事、像素艺术头像、专属配色——5 个职业模板开箱可用。ReAct + Plan-and-Execute 双模式，员工之间并行委派。 + details: 你雇佣同事，不是开聊天框。每位有角色 / 目标 / 背景故事、像素艺术头像与专属配色——6 个内置模板开箱可用。ReAct + Plan-and-Execute 双模式，员工之间并行委派。 - icon: 🤝 title: 团队，不是单打独斗 - details: 建一个团队：Lead 把目标拆成任务落到共享任务板，成员并行执行，依赖自动编排、前置结果自动传递、结果自动通报汇总。执行租约、取消即中断、审批卡点、交付物与任务时间线——2.0.0 起，一支队伍围着一块看板干活。 + details: 一次团队请求对应一个 Team Run：目标、任务 DAG、成员执行、最终汇总与交付物统一追踪。Chat 交付成果、Agents 观察实时运行、Teams 管理历史与审批——2.1.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/intro.md b/mateclaw-server/src/main/resources/docs/zh/intro.md index c6391f02..792fade7 100644 --- a/mateclaw-server/src/main/resources/docs/zh/intro.md +++ b/mateclaw-server/src/main/resources/docs/zh/intro.md @@ -1,6 +1,6 @@ --- title: MateClaw 项目介绍 — 自部署多智能体 AI 操作系统 -description: MateClaw 是基于 Spring AI Alibaba 的开源多智能体 AI 操作系统。ReAct + Plan-and-Execute 双引擎、LLM Wiki 知识库、四层记忆系统、MCP 工具协议、8 渠道统一接入。一个 JAR 包自部署，数据不出门。 +description: MateClaw 是基于 Spring AI Alibaba 的开源多智能体 AI 操作系统。ReAct + Plan-and-Execute 双引擎、LLM Wiki 知识库、四层记忆系统、MCP 工具协议、8 渠道统一接入。一个 JAR 包自部署，数据与外发集成边界由你掌控。 head: - - meta - name: keywords @@ -11,7 +11,7 @@ head: **你的多智能体 AI，跑在你自己的机器上，按你自己的规则。** -MateClaw 是一整套可以自部署的 AI 操作系统。一个 JAR 包，一套登录，数据不出门。 +MateClaw 是一整套可以自部署的 AI 操作系统。一个 JAR 包，一套登录，持久化数据和外发集成由你掌控。 **它和别的 AI 不一样的三件事——** @@ -55,13 +55,13 @@ MateClaw 换了一个打法：**所有东西放在一个屋檐下，跑在你自 把 MateClaw 跑在你自己的机器上，不是合规打个勾那么简单。它改变的是这个产品**到底是什么**。 -**你的数据不再给别人付房租。** 对话、日志、文档、记忆——没有一条拿去训练别人的模型，没有一条在别人家的队列里排队，没有一条离开你的机器，除非是你自己把某个渠道接了出去。 +**你掌控数据与外发边界。** 对话、日志、文档和记忆持久化在自己的部署中；只有完成任务所需的内容会发送到你主动配置的云模型、IM 渠道、MCP 或其他工具服务。需要完全本地处理时，可以组合本地模型与本地工具，并关闭外部集成。 **路线图是你的。** 记忆整合的规则你不喜欢？自己改。需要一个厂商不给你做的工具？自己加。Apache 2.0，不是 "source available"，不是 "open core"，不用等别人的季度产品评审。 **账单是你自己算的。** 一开始上 DashScope，等本地 GPU 到了就切 Ollama，某个高价值 Agent 单独挂 OpenAI，其他的走便宜的。Agent 配置和工具图不关心底下的模型接口是什么。 -**部署面是实打实的。** 一个 JAR 包。一个 Spring Boot 进程。不用装 Python，不用装 Node。桌面端自己带环境，Docker Compose 一共 18 行。 +**部署面是实打实的。** 一个 JAR 包。一个 Spring Boot 进程。运行服务不要求额外安装 Python 或 Node。桌面端自带 JRE，Docker Compose 一条命令启动 PostgreSQL、SearXNG 与服务端。 --- @@ -71,7 +71,7 @@ MateClaw 换了一个打法：**所有东西放在一个屋檐下，跑在你自 - **前端**——Vue 3 + TypeScript。Pinia 管状态，Element Plus + Tailwind 做 UI，支持深色模式。前端 build 的产物直接进后端 JAR 的 `static/`，一个进程服务两端。 - **桌面端**——Electron 包 JRE 21 + 后端 JAR。双击启动，用户完全不需要知道底下跑的是 Java。 - **渠道**——每个渠道是一个 `ChannelAdapter` SPI 实现。Web 走 SSE，IM 各自走平台的长连接或 webhook。 -- **存储**——开发用 H2 文件数据库，生产用 MySQL 8。Flyway 管理 schema 迁移，每种方言各有一套脚本。 +- **存储**——开发与桌面端默认使用 H2 文件数据库；公开 Docker 栈默认使用 PostgreSQL 16；MySQL 8 profile 继续支持，KingbaseES 驱动按需启用。Flyway 按数据库方言管理 schema 迁移。 --- diff --git a/mateclaw-server/src/main/resources/docs/zh/models.md b/mateclaw-server/src/main/resources/docs/zh/models.md index 847245fc..376f15c7 100644 --- a/mateclaw-server/src/main/resources/docs/zh/models.md +++ b/mateclaw-server/src/main/resources/docs/zh/models.md @@ -509,6 +509,19 @@ LLM API Key **不再读取环境变量**——`DASHSCOPE_API_KEY` / `OPENAI_API_ --- +## 单模型上下文窗口（2.1.0+） + +MateClaw 不再把所有模型统一当作 128K。运行时预算解析顺序是：**管理员覆盖值 → 本地模型实时探测或供应商超限反馈的短期缓存 → 内置模型目录 → 原有全局默认值**。模型列表为了避免 I/O，只显示覆盖值或目录值；未知模型仍由调用方使用全局默认。这会直接影响系统提示词、记忆、Wiki、历史消息与工具 schema 的预算分配。 + +- 已知模型（含 GLM-5V-Turbo、Kimi coding alias 等）自动使用目录窗口； +- 自定义/私有模型可在模型管理页填写准确的最大输入 token； +- API 使用 `PUT /api/v1/models/{providerId}/models/context-window`，请求体为 `modelId` 和 `maxInputTokens`；空值或非正数会清除覆盖； +- 工作空间成员读取 provider 绑定选项时只得到 id/显示名，不暴露 key、base URL 等连接配置。 + +OpenAI 兼容链路同时保留工具 JSON Schema 中的 `integer` / `number`。`generateKwargs` 只把顶层非保留键原样透传到请求体；temperature、token 上限、`topP`、`reasoningEffort`、搜索、headers 与 path 等保留键由统一读取器处理。未知的嵌套 `chatOptions` 键不会透传，`reasoningEffort` 仅发送给明确支持的模型族。 + +--- + ## 下一步 - [配置说明](./config)——完整配置参考 diff --git a/mateclaw-server/src/main/resources/docs/zh/quickstart.md b/mateclaw-server/src/main/resources/docs/zh/quickstart.md index b96a5920..db97d48d 100644 --- a/mateclaw-server/src/main/resources/docs/zh/quickstart.md +++ b/mateclaw-server/src/main/resources/docs/zh/quickstart.md @@ -78,7 +78,7 @@ Docker 和源码启动在 [配置说明](./config) 和 [贡献指南](./contribu ## 其他部署方式 - **Docker**——`cp .env.example .env` 填好密码，`docker compose up -d --build`。完整的前置要求、Maven 镜像选择（中国 / 美国）、浏览器工具自检、升级流程看 [Docker 部署](./docker-deploy)。 -- **从源码跑**——`mateclaw-server/` 里 `mvn spring-boot:run`，`mateclaw-ui/` 里 `pnpm dev`。细节在 [贡献指南](./contributing)。 +- **从源码跑**——`mateclaw-server/` 里 `mvn spring-boot:run`，`mateclaw-ui/` 里 `npm run dev`。细节在 [贡献指南](./contributing)。 - **桌面端内部**——打包、签名、自动更新。看 [桌面应用](./desktop)。 --- diff --git a/mateclaw-server/src/main/resources/docs/zh/releases.md b/mateclaw-server/src/main/resources/docs/zh/releases.md index 00b1bcc5..bce87686 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.1.0](./releases/2.1.0) | 2026-08-15 | **统一 Team Run**——一次团队请求、任务 DAG、成员执行、最终汇总与交付物共用 `runId`，Chat 成果交付 / Agents 实时观察 / Teams 历史治理读取同一投影，成员子会话不再污染普通会话列表 · **Skill 自进化闭环**（跨会话重复请求 mining · reflection · 受约束自动绑定 · curator 治理移交 · origin 策略 · 快照与恢复点，按工作空间隔离且默认保守） · **推理轨迹可回放**（实时 `` 提取 · UI 真实耗时 · 全部/最终轮次控制 · 纯文本 trajectory 导出） · 主动渠道消息 + Cron 定向投递 · 模型窗口覆盖/探测/目录预算 · 渐进式工具桥 + 行动完成约束 · 浏览器 ref/导航/等待加固 · WebChat/SSE/LLM 流回收与超时 · 飞书执行进度 · Qwen3-ASR HTTP · 会话批量删除 · 按日文件目录 · 64 位 id 与数值工具 schema 精度修复 | | [v2.0.0](./releases/2.0.0) | 2026-07-31 | **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 可调试 | diff --git a/mateclaw-server/src/main/resources/docs/zh/roadmap.md b/mateclaw-server/src/main/resources/docs/zh/roadmap.md index 07791a73..4b542e74 100644 --- a/mateclaw-server/src/main/resources/docs/zh/roadmap.md +++ b/mateclaw-server/src/main/resources/docs/zh/roadmap.md @@ -130,7 +130,7 @@ MateClaw 就是这个东西。 完整故事：[v1.8.0 Release Notes](./releases/1.8.0.md)。 -### v2.0 —— 它带队干活 ✅ 已发布（2026-07-26） +### v2.0 —— 它带队干活 ✅ 已发布（2026-07-31） 从"一个能干活的人"到"一支能协作的队伍"——**Agent 团队**成为常设编制，围着一块共享任务板协作。 @@ -143,13 +143,26 @@ MateClaw 就是这个东西。 完整故事：[v2.0.0 Release Notes](./releases/2.0.0.md)，使用指南：[团队协作](./teams)。 +### v2.1 —— 它把团队工作变成可治理的运行 ✅ 已发布（2026-08-15） + +2.0 建好了团队和任务板，2.1 把长期使用后暴露的三条链合流：**一次团队请求有统一身份、一次执行有可回放轨迹、一项技能改进有来源和恢复点**。 + +- **统一 Team Run**：一个 `runId` 串起用户请求、任务 DAG、成员执行、最终汇总与交付物；Chat 交付、Agents 观察、Teams 治理读取同一投影 +- **成果优先的交付体验**：团队 worker 会话退出普通侧栏，中间通报合并，最终摘要、文件、异常和审批优先，过程逐层下钻 +- **Skill 自进化闭环**：reflection + 跨会话重复请求 mining + promotion + 受约束自动绑定 + curator 治理移交 + snapshot/restore；reflection/routine 默认关闭，curator 激活前只预览，按工作空间隔离且可回滚 +- **推理与执行可回放**：每轮 thinking、真实耗时、tool/observation 顺序、superseded 叙述与线性 trajectory 导出 +- **能力到达真实现场**：主动渠道消息、Cron 定向投递、模型级上下文窗口、渐进式工具桥、行动完成约束 +- 浏览器、WebChat/SSE、飞书进度、Qwen3-ASR、文件目录与 64 位 id 精度全面加固 + +完整故事：[v2.1.0 Release Notes](./releases/2.1.0.md)，使用指南：[Team Run 与团队协作](./teams)、[技能系统](./skills)。 + --- ## 下一站：Agent Loop 与团队进阶 > "伟大的事业不是一个人做成的，是一个团队做成的。" -回头看这条线：v1.2 员工有了身份，v1.3 流程能编排，v1.4 员工会自主跟目标、能临时拉起委派树，v1.7 长任务看得见，**v2.0 团队成了常设编制**。 +回头看这条线：v1.2 员工有了身份，v1.3 流程能编排，v1.4 员工会自主跟目标、能临时拉起委派树，v1.7 长任务看得见，v2.0 团队成了常设编制，**v2.1 又让每轮团队工作可交付、可学习、可治理**。 还剩一个"停"：**员工是被动的。** 目标的自动延续只活在**单次运行内**；cron 和触发器能定时叫醒它，但每次醒来都是一次孤立的响应。没有一个员工真正"在岗"——持续盯着自己的职责范围，自己决定什么时候该干什么。 @@ -225,6 +238,7 @@ MateClaw 就是这个东西。 | **v1.7** | 它敢放进生产 | 审批三链路闭环 + 运行总览与成本可见 + 上下文/Token 预算 + 开放 API/Deep Research + 桌面远程/局域网 + 运营导出 | ✅ 已发布 | | **v1.8** | 它干完一整件活 | 内容工作室 —— 一句话到可发布的公众号 / 小红书成品 + 浏览器 ref 交互 | ✅ 已发布 | | **v2.0** | **它带队干活** | **Agent 团队 + 共享任务板 —— Lead 拆解派发、成员并行执行、交付物与全程可观测** | ✅ 已发布 | +| **v2.1** | **它把协作变成运行** | **统一 Team Run + Skill 自进化闭环 + 可回放推理轨迹 + 主动渠道投递** | ✅ 已发布 | | **下一站** | **它长期在岗** | **Agent Loop 常驻循环 + 团队进阶（互审 / 团队目标 / 群绑定 / 复盘）= 会自己运转的数字部门** | 📋 规划中 | --- @@ -237,7 +251,7 @@ MateClaw 就是这个东西。 **AI 不应该是一个网页上的对话框。它应该是你的第二个大脑。** -它住在你的钉钉里、你的飞书里、你的 Telegram 里。它读过你所有的文档。它记得你三个月前说过的话。它会用你公司的内部工具。它在你睡觉的时候整理记忆。它能替你跑一整条业务流程。**很快，它还会带着一支常设团队，长期在岗，替你盯着那些你顾不上的事。** +它住在你的钉钉里、你的飞书里、你的 Telegram 里。它读过你所有的文档。它记得你三个月前说过的话。它会用你公司的内部工具。它在你睡觉的时候整理记忆。它能替你跑一整条业务流程。**现在它已经能把一轮团队工作完整交付并从中学习；下一步，是让这支团队长期在岗，替你盯着那些你顾不上的事。** 总有一天，你会忘记它是一个程序。 diff --git a/mateclaw-server/src/main/resources/docs/zh/security.md b/mateclaw-server/src/main/resources/docs/zh/security.md index 38b8e8d1..a894f87e 100644 --- a/mateclaw-server/src/main/resources/docs/zh/security.md +++ b/mateclaw-server/src/main/resources/docs/zh/security.md @@ -494,7 +494,7 @@ curl "http://localhost:18088/api/v1/audit/events?from=2026-04-01&to=2026-04-11&a | **关掉 H2 console** | 生产环境 `spring.h2.console.enabled=false` | | **防火墙** | 只开放对外端口 | | **限流** | 在反向代理层配置 | -| **MySQL，不是 H2** | 生产用独立的 MySQL 8 实例 | +| **生产数据库，不用 H2** | 推荐按公开 Docker 栈使用 PostgreSQL 16；也支持独立 MySQL 8 或 KingbaseES | ### Nginx 反向代理示例 diff --git a/mateclaw-server/src/main/resources/docs/zh/skills.md b/mateclaw-server/src/main/resources/docs/zh/skills.md index c81e1042..669332e6 100644 --- a/mateclaw-server/src/main/resources/docs/zh/skills.md +++ b/mateclaw-server/src/main/resources/docs/zh/skills.md @@ -675,6 +675,24 @@ MCP / ACP 衍生的技能过去是不透明的工具包，没有可读指令。v --- +## Skill 自进化闭环（2.1.0+） + +2.1.0 把“写入 LESSONS.md”扩展成一条可观察、可恢复的持续改进链： + +1. **Reflection** 从已完成对话中提出精确 patch 或新技能候选； +2. **Routine mining** 按员工聚类最近会话的首条用户请求，而不是完整执行轨迹。默认回看 30 天，至少 3 次且跨 3 个自然日才达晋升门槛；启用后的夜间任务会自动晋升达标候选（默认每轮最多 2 个），管理员也可提前晋升、忽略或重开； +3. **自动绑定** 只处理带来源员工的新技能，并且仅在该员工已经使用显式非空技能 allowlist 时补绑定。继承全部技能无需绑定，显式禁用技能不会被后台改写； +4. **Curator** 按工作空间整理 stale / archived / 可合并技能。它初始只做预览，管理员激活后才修改；consolidation 另行开启，合并与来源归档事务化； +5. **Adopt / release** 是治理权移交：adopt 把 user 技能纳入自治治理，release 把它归还用户所有，不表示“某员工采用了该技能”； +6. **Snapshot** 在每次已激活的变更 sweep 前建立恢复点，恢复前也会再建快照，默认每个工作空间保留 5 个； +7. **Origin** 区分 builtin、user、agent 和 routine，同时作为 curator 的策略边界；手动移交会有意改变 user / agent 状态。 + +安全默认值是**先观察、再允许自动写入**：reflection 和 routine mining 默认关闭。Reflection 的 `enabled` 控制是否把对话与技能目录交给审阅模型，`auto-apply` 再独立控制是否落库；关闭自动应用时不会修改技能，但也没有持久化的人工批准队列。对话与技能内容作为不可信数据处理，自动写入只允许 create 或唯一上下文 patch。整篇覆盖、秘密外发、绕过审批、跨工作空间读取/修改都会 fail closed。 + +控制台「设置 → 技能管理员」可查看工作空间状态、候选 routine、最近报告、来源、已纳管/未纳管技能与恢复点。所有 curator、routine、snapshot、adopt/release 接口都要求当前工作空间上下文。 + +--- + ## 下一步 - [工具系统](./tools)——技能能用的工具 diff --git a/mateclaw-server/src/main/resources/docs/zh/teams.md b/mateclaw-server/src/main/resources/docs/zh/teams.md index 65a302cd..247fb3af 100644 --- a/mateclaw-server/src/main/resources/docs/zh/teams.md +++ b/mateclaw-server/src/main/resources/docs/zh/teams.md @@ -1,13 +1,13 @@ --- -title: 团队协作 — 一个 Lead 带一群数字员工，在共享任务板上并行干活 -description: MateClaw 的 Agent 团队让一个 Lead 员工把复杂目标拆成任务、派给团队成员并行执行，任务板负责依赖、审批、交付物与全程可观测。 +title: Team Run — 从一次团队请求到可追踪、可交付的完整运行 +description: MateClaw Team Run 用一个 runId 串起 Lead、任务 DAG、成员执行、最终汇总与交付物，并在 Chat、Agents、Teams 三个页面提供统一视图。 head: - - meta - name: keywords content: Agent团队,任务板,看板,多Agent协作,派发,交付物,团队协作,MateClaw --- -# 团队协作（2.0.0+） +# Team Run 与团队协作（2.1.0+） > **以前是"一个员工带子任务"。现在是"一个团队围着一块任务板"。** @@ -15,6 +15,32 @@ head: 团队协作把这套项目机制搬进 MateClaw：你建一个**团队**，指定一个 **Lead** 员工、若干**成员**员工；对 Lead 说一句目标，它把目标拆成任务落到**共享任务板**上；派发引擎把任务自动分给成员**并行执行**；成员完成后结果自动通报回 Lead，由它汇总、补派、直到整件事干完。你全程在 Teams 页旁观——或者直接往板上投任务。 +2.1.0 在任务之上增加一等对象 **Team Run**：一条用户请求只对应一轮运行，一个 `runId` 串起原始目标、任务 DAG、成员子会话、事件、最终汇总与交付物。你看到的不再是一堆叫“子任务”的会话，而是一份结果优先、可以下钻的完整工作记录。 + +## 2.1.0 的统一 Team Run 体验 + +| 页面 | 职责 | 默认看到什么 | +|------|------|--------------| +| **Chat** | 成果交付面 | 一张稳定的运行卡片：统一状态与进度、最终摘要、交付物、失败或待审批事项；任务过程按需展开 | +| **Agents · Live** | 实时观察面 | 同一 `runId` 下的成员按运行分组，显示当前任务、phase、工具、耗时和异常；普通非团队运行保持独立 | +| **Teams** | 历史与治理面 | 团队运行历史、运行详情、任务证据、审批、取消与成员执行记录，不再把所有历史任务平铺成主视图 | + +Team Run 状态由服务端统一投影： + +```text +planning → running → awaiting_review → finalizing → completed + ↘ partial / failed +planning / running / awaiting_review → cancelled +``` + +- **一事一身份**：SSE 事件、页面路由、日志、任务和最终消息都携带 `runId`； +- **成果优先**：中间任务完成只更新运行进度，不为每个任务制造一条面向用户的最终回复； +- **子会话治理**：`team_worker` 会话不进入普通会话侧栏；深链接仍可打开，但以只读执行记录呈现并提供返回 Team Run 的入口； +- **刷新可恢复**：页面只消费后端 `TeamRunView`，标题、状态、进度、摘要和文件不会因前端重算而漂移； +- **历史兼容**：2.0.0 创建、没有 `runId` 的任务继续可查，但不会按时间窗口被错误拼成一次运行。 + +运行协议固定为 `start_run → create* → seal_run`：Lead 先建立运行，再创建显式归属该运行的任务，最后封板开始派发。来源消息参与幂等约束，重连或重复提交不会再造出第二轮相同运行。 + --- ## 核心概念 @@ -122,6 +148,10 @@ Lead 不限定 Agent 类型。**ReAct 型 Lead** 用 `team_tasks` 逐条建任 | 端点 | 说明 | |------|------| +| `GET /api/v1/team-runs/{runId}` | 读取完整运行投影 | +| `GET /api/v1/teams/{teamId}/runs` · `GET …/runs/page` | 列出 / 按游标读取团队运行历史 | +| `GET /api/v1/conversations/{conversationId}/team-runs` · `GET …/team-runs/page` | 列出 / 按游标读取父对话中的 Team Run | +| `POST /api/v1/team-runs/{runId}/cancel` | 取消运行及其未终态任务 | | `GET / POST /api/v1/teams` | 列出 / 创建团队 | | `GET / PUT / DELETE /api/v1/teams/{id}` | 团队详情 / 更新 / 删除 | | `POST /api/v1/teams/{id}/members` · `DELETE …/members/{agentId}` | 成员增删 | @@ -135,7 +165,7 @@ Lead 不限定 Agent 类型。**ReAct 型 Lead** 用 `team_tasks` 逐条建任 所有校验失败都以**可读错误**返回——不是裸 500。 -数据落五张表：`mate_agent_team`、`mate_agent_team_member`、`mate_team_task`、`mate_team_task_comment`、`mate_team_task_event`。 +数据在原有五张团队表之上新增 `mate_team_run`，`mate_team_task.run_id` 与成员会话索引负责把任务、运行和执行记录关联起来。所有 Snowflake id 在 JSON 边界按字符串返回。 --- diff --git a/mateclaw-server/src/main/resources/docs/zh/tools.md b/mateclaw-server/src/main/resources/docs/zh/tools.md index eec59479..13162340 100644 --- a/mateclaw-server/src/main/resources/docs/zh/tools.md +++ b/mateclaw-server/src/main/resources/docs/zh/tools.md @@ -382,6 +382,18 @@ public class FactorialTool { --- +## 2.1.0：渐进式工具桥与行动完成约束 + +工具很多时，MateClaw 先暴露轻量目录，再按当前任务需要展开具体 schema。渐进式工具桥减少上下文占用，也避免一次把数百个参数塞给模型；显式启用后的工具名会缓存和规范化，长循环里不重复扫描 MCP 热路径。 + +行动型请求还增加了完成约束：当用户要求“发送、创建、删除、查询外部系统、打开网页执行”等真实动作时，如果运行账本没有记录成功的实质性工具调用，系统会要求模型再尝试一次；仍未调用时以 `action_unverified` 收尾，工具已尝试但失败时以 `action_failed` 收尾，而不是声称“已完成”。当前约束验证的是“存在成功的实质性调用”，并不做工具结果与用户目标之间的语义等价证明。只读解释和无需工具的回答不受影响。 + +`browser_use` 在 2.1.0 加固了 ref 生命周期、导航安全、会话门、等待条件和快照：页面变化后旧 ref 会明确失效，导航与等待结果返回可诊断状态，避免点错旧元素或多个浏览器会话互相覆盖。 + +主动消息工具 `list_channel_sessions` / `send_channel_message` 只向当前工作空间内已验证的渠道会话推送；使用方式见 [多渠道接入](./channels)。 + +--- + ## 下一步 - [技能系统](./skills)——建立在工具之上的更高层能力 diff --git a/mateclaw-ui/package.json b/mateclaw-ui/package.json index aae0d30f..c57cc48c 100644 --- a/mateclaw-ui/package.json +++ b/mateclaw-ui/package.json @@ -1,6 +1,6 @@ { "name": "mateclaw-ui", - "version": "2.1.0-SNAPSHOT", + "version": "2.1.0", "private": true, "type": "module", "description": "MateClaw - Personal AI Assistant Web Console", diff --git a/pom.xml b/pom.xml index 52aa93eb..f3133720 100644 --- a/pom.xml +++ b/pom.xml @@ -23,7 +23,7 @@ - 2.1.0-SNAPSHOT + 2.1.0 21