From d7d409245bf7b6e7aa87b1e25eb00c03925d8e71 Mon Sep 17 00:00:00 2001 From: matevip Date: Thu, 25 Jun 2026 17:26:33 +0800 Subject: [PATCH] docs: feature-page coverage for 1.7.0 (operational export, desktop remote, webchat approval, run overview, workflow notify) --- .../src/main/resources/docs/en/chat.md | 11 +++ .../src/main/resources/docs/en/desktop.md | 22 ++++++ .../resources/docs/en/operational-export.md | 77 +++++++++++++++++++ .../src/main/resources/docs/en/webchat.md | 27 +++++++ .../src/main/resources/docs/en/workflow.md | 6 ++ .../src/main/resources/docs/zh/chat.md | 11 +++ .../src/main/resources/docs/zh/desktop.md | 22 ++++++ .../resources/docs/zh/operational-export.md | 77 +++++++++++++++++++ .../src/main/resources/docs/zh/webchat.md | 27 +++++++ .../src/main/resources/docs/zh/workflow.md | 6 ++ 10 files changed, 286 insertions(+) create mode 100644 mateclaw-server/src/main/resources/docs/en/operational-export.md create mode 100644 mateclaw-server/src/main/resources/docs/zh/operational-export.md diff --git a/mateclaw-server/src/main/resources/docs/en/chat.md b/mateclaw-server/src/main/resources/docs/en/chat.md index de586300..601b0a2d 100644 --- a/mateclaw-server/src/main/resources/docs/en/chat.md +++ b/mateclaw-server/src/main/resources/docs/en/chat.md @@ -40,6 +40,17 @@ Use Plan-and-Execute when the task needs several ordered steps and you want to w --- +## Run Overview: see the whole long task at a glance + +Long tasks (multi-step plans, multi-agent collaboration) used to mean scrolling up and down the message stream to track progress. The chat view now has an always-on **Run Overview** rail on the right that assembles the data the backend already streams into one place — no scrolling back: + +- **Plan progress** — in Plan mode, live per-step status (pending / running / completed) and a progress count, with expandable step results. A "planning…" placeholder shows before the plan streams in, so the rail doesn't flicker. +- **Live sub-agent status** — delegated sub-agents render as a live **tree**: name, tools called, running / completed / error / stalled state; multi-level delegation expands layer by layer. + +The rail **collapses to a badged strip**; below 1280px it degrades to a **floating drawer** so it never squeezes the conversation column. It's pure frontend with zero new endpoints, reusing the existing SSE event stream — so the delegation tree still appears inline in the message too; the rail just lifts the "current / active" overview into a persistent place. + +--- + ## Thinking, tool calls, and what to trust One of the questions MateClaw tries to answer with its chat UI is: **should you trust what the AI just told you?** The default answer elsewhere is "look at the answer and guess". MateClaw tries to do better. diff --git a/mateclaw-server/src/main/resources/docs/en/desktop.md b/mateclaw-server/src/main/resources/docs/en/desktop.md index 0af5733f..300d4023 100644 --- a/mateclaw-server/src/main/resources/docs/en/desktop.md +++ b/mateclaw-server/src/main/resources/docs/en/desktop.md @@ -50,10 +50,32 @@ The backend picks a **free port dynamically** at startup so you don't collide wi - **Local-first data** — everything in a user directory - **Dynamic backend port** — no port collisions - **UI hot update** — frontend assets can be updated without repackaging the installer +- **Local / remote dual connection mode** — run the embedded JVM locally, or connect to a centrally deployed remote server - Cross-platform (macOS, Windows, Linux) --- +## Connection mode (local / remote) + +> For the "a team collaborating against one centrally deployed server" scenario — no need for everyone to run their own local backend. + +The desktop reaches its backend in one of two ways: + +- **Local (`local`)** — launches the embedded JRE 21 + server JAR and runs a full backend on this machine (default, works out of the box). +- **Remote (`remote`)** — skips the local backend and connects directly to your centrally deployed remote server; all API / SSE point at it. + +**First-run connection chooser.** The first launch (no mode chosen yet) shows a connection chooser; picking "remote" lets you enter the server URL, which is normalized (auto-prefixes `https://`, strips a trailing slash, validates http(s)). The choice is remembered for next time. + +**Multi-server & switching.** A successfully connected remote server is recorded in a "recently used" list (de-duped by URL, up to 8). The **"Switch Server"** menu re-opens the chooser anytime to move to another server. + +**Self-signed intranet certs.** Self-signed certificates are accepted only for hosts the user **explicitly trusts** — scoped to the active remote address (`trustedCertHosts`), not a blanket bypass; unknown hosts are rejected. This suits the self-signed certs common on enterprise intranets. + +**Health check.** Remote mode probes with a short timeout (~15s) since the server should already be up, and reports failures clearly; local mode waits for the embedded backend to come up. + +The connection choice is persisted in `connection.json` under the user data directory (see "Data storage" below). + +--- + ## Supported platforms | Platform | Architecture | Status | diff --git a/mateclaw-server/src/main/resources/docs/en/operational-export.md b/mateclaw-server/src/main/resources/docs/en/operational-export.md new file mode 100644 index 00000000..78f4b7a4 --- /dev/null +++ b/mateclaw-server/src/main/resources/docs/en/operational-export.md @@ -0,0 +1,77 @@ +# Operational Data Export + +Export a cross-cutting operational report as Excel (`.xlsx` packaged as `.zip`) in one shot, for ops, audit, and reconciliation offline. Two entry points: a **Dashboard one-click** export (GUI) and a **command-line** export (no UI, works via `docker exec`). + +> **Global admin only.** The report contains sensitive cross-workspace data — conversation contents, token usage, audit records, etc. + +## The 9 sheets + +| # | Sheet | Contents | +|---|---|---| +| 1 | Overview | Interval KPIs, system snapshot, 7-day trend, period comparison, model details, top-10 agent activity | +| 2 | Token Usage | Daily × `runtime_provider` breakdown with avg tokens/conversation | +| 3 | Skill Stats | Skill list + usage count, last-call time, bound agents | +| 4 | User Stats | Per-(workspace, user) aggregated tokens, duration, last active | +| 5 | User Conversations | Detail rows pairing user–assistant messages | +| 6 | Security & Audit | Unified view across 6 sources (guard rules, audit logs, approvals, grants, config, business audit events) | +| 7 | Channel Stats | Per-channel conversation count, tokens, unique users | +| 8 | Model Config | Enabled + API-key-configured models with parameters | +| 9 | Cron Jobs | Execution records with duration and token usage | + +## Entry 1: Dashboard one-click + +1. Open the **Dashboard** and click **"Export operational data"** in the top-right (next to the database chip) — visible to global admins only. +2. In the dialog pick a **date range** — use the quick "Last 7 / 30 / 90 days" presets or a custom range; **90-day max**, no future dates. +3. Click **"Generate report"** — a circular progress ring shows the 9 steps (Overview → … → Cron Jobs). +4. When done, "Report is ready" appears; click **"Download"** to get `ops_data__.zip`. + +**Security & lifecycle:** + +- The generate / progress / download endpoints are all `@RequireGlobalAdmin` gated — a non-admin call returns 403. +- Only one generation runs at a time (concurrent calls get 409 busy), with a 5-minute frontend deadline. +- The download token is **atomically single-use** — a second download with the same token returns 410. +- The generated file auto-cleans **after 24h or on download**. + +## Entry 2: Command line + +For large, no-timeout, scripted, `docker exec` scenarios. A project-level CLI framework was added; the export command is `--cli.command=export`: + +```bash +# local jar +java -jar app.jar --cli.command=export \ + --cli.start=2026-01-01 --cli.end=2026-06-30 > report.zip + +# inside a container +docker exec java -jar /app/app.jar --cli.command=export \ + --cli.start=2026-01-01 --cli.end=2026-06-30 > report.zip + +# dry run (no actual generation) +java -jar app.jar --cli.command=export --cli.start=... --cli.end=... --cli.dry-run + +# list all commands +java -jar app.jar --cli.command=help +``` + +| Option | Required | Meaning | +|---|---|---| +| `--cli.command=export` | yes | run the export command | +| `--cli.start=YYYY-MM-DD` | yes | start date (inclusive) | +| `--cli.end=YYYY-MM-DD` | yes | end date (inclusive) | +| `--cli.dry-run` | no | dry-run, no actual generation | + +Key points: + +- The ZIP bytes go straight to **stdout** (redirect with `> report.zip`); diagnostics go to **stderr**, so the redirect captures a clean binary. +- The backend entry point has **no 90-day cap and no timeout** — suitable for large offline ranges. +- The CLI is operator-only (local / `docker exec`), **never over HTTP**, and does not bypass the admin gate. +- On a normal web start (no `--cli.command`) the CLI stays inert and does not affect startup. + +## Notes + +- 19-digit Snowflake IDs are written to Excel as **text** to avoid the spreadsheet's numeric precision (2^53) truncating them or showing scientific notation. +- The report grows with your data; when exporting a large range from the CLI, redirect straight to a file rather than piping to another program. + +## See also + +- [Backstage Runtime Console](./backstage) — see live agents / sub-agents +- [Security & Approval](./security) — Tool Guard and audit logs (one source of Sheet 6) diff --git a/mateclaw-server/src/main/resources/docs/en/webchat.md b/mateclaw-server/src/main/resources/docs/en/webchat.md index c373e40a..a1cf1a15 100644 --- a/mateclaw-server/src/main/resources/docs/en/webchat.md +++ b/mateclaw-server/src/main/resources/docs/en/webchat.md @@ -77,6 +77,8 @@ init({ apiKey: 'your-channel-api-key', server: 'https://' }) | DELETE | `/sessions` | + visitorToken | Delete | | POST | `/sessions/stop` | + visitorToken | Stop an in-flight stream | | POST | `/sessions/regenerate` | + visitorToken | Regenerate the last assistant reply | +| POST | `/sessions/approve` | + visitorToken | Approve a pending tool approval and replay (SSE) | +| POST | `/sessions/deny` | + visitorToken | Deny a pending tool approval (synchronous JSON) | | GET | `/sessions/messages` | + visitorToken | Message list (paginated) | | POST | `/upload` | + visitorToken | Upload an attachment (returns fileId) | | GET | `/files` | + visitorToken | Download a file (uploaded or agent-generated) | @@ -186,6 +188,31 @@ data: {"message":"..."} (on failure) Each session returned by `/sessions` includes: `sessionId`, `title`, `lastActiveTime`, `messageCount`, `pinned`, `archived`, `streamStatus` (`running` / `idle`). +## Tool approval resolve (API-Key channel) + +When an agent bound to WebChat calls a tool protected by [Tool Guard](./security), that turn **suspends waiting for approval**. The visitor can approve or deny it in-session instead of letting it time out. + +- **Approve** `POST /sessions/approve` — with `sessionId` + `pendingId`. Auth reuses visitorToken + conversation ownership; the `pendingId` is **strictly validated to belong to this session** (else 404), closing a cross-visitor IDOR. Approving **replays** the suspended tool call and resumes as SSE. +- **Deny** `POST /sessions/deny` — with `sessionId` + `pendingId`, returns synchronous JSON, no replay. + +Both broadcast a `tool_approval_resolved` SSE event (see [Optional realtime progress events](#optional-realtime-progress-events) above) so the SDK / frontend clears the approval banner in real time. + +> Whether an approval appears depends on whether the agent's bound Tool Guard rules set `require_approval` for some tool. Get `pendingId` from the `tool_approval_requested` event. + +```bash +# Approve (resumes as SSE) +curl -N -X POST "https://mate.example.com/api/v1/channels/webchat/sessions/approve" \ + -H "X-MC-Key: " -H "X-Visitor-Token: " \ + -H "Content-Type: application/json" \ + -d '{"sessionId":"s1","pendingId":""}' + +# Deny (synchronous JSON) +curl -X POST "https://mate.example.com/api/v1/channels/webchat/sessions/deny" \ + -H "X-MC-Key: " -H "X-Visitor-Token: " \ + -H "Content-Type: application/json" \ + -d '{"sessionId":"s1","pendingId":""}' +``` + ## visitorToken revocation (admin) A visitor abusing the channel? An admin calls: diff --git a/mateclaw-server/src/main/resources/docs/en/workflow.md b/mateclaw-server/src/main/resources/docs/en/workflow.md index 16042d49..45701afc 100644 --- a/mateclaw-server/src/main/resources/docs/en/workflow.md +++ b/mateclaw-server/src/main/resources/docs/en/workflow.md @@ -98,6 +98,12 @@ How it reads: > **Not in v1.3.0**: `loop` (iterate N times or per-item over an array) and `invoke_skill` (call a skill without going through an employee). Coming based on user feedback. +> **`await_approval` channel notifications (actually delivered since 1.7.0)**: each element of `approverChannels[]` is either +> - `"channelType"` (e.g. `"web"`) — **not actively pushed**; resolve from the admin side; or +> - `"channelType:targetId"` (e.g. `"feishu:oc_xxx"`, `"wecom:xxx"`) — **pushes an approval notification** to that target (Feishu/WeCom group). +> +> Once approved, the workflow **resumes from the paused step automatically** (the resolve → resume bridge). In a Feishu/WeCom group you can **tap the card's Approve/Deny button** to resolve it directly. See [Approval & security](./security). + ### Expressions: a Pebble subset Workflow does **not** use a full template engine — it supports the same Pebble subset as Kestra, just enough to gate conditionals and reference variables, with no code execution. diff --git a/mateclaw-server/src/main/resources/docs/zh/chat.md b/mateclaw-server/src/main/resources/docs/zh/chat.md index 2910ca2b..7981b646 100644 --- a/mateclaw-server/src/main/resources/docs/zh/chat.md +++ b/mateclaw-server/src/main/resources/docs/zh/chat.md @@ -40,6 +40,17 @@ Segment 是**渐进到达**的。每个 segment 一落盘就立刻持久化到 --- +## 运行总览：长任务一眼看全 + +长任务（多步骤计划、多智能体协同）以前只能在消息流里上下翻找进度。聊天页右侧现在有一个常驻的**「运行总览」侧栏**，把后端本就在流式推送的数据装配到一处，不必翻历史： + +- **计划进度** —— Plan 模式下实时显示各步骤状态（待执行 / 执行中 / 已完成）、进度计数，步骤结果可展开。计划生成前显示「规划中…」占位，不再闪烁。 +- **子 Agent 实时状态** —— 委派产生的子 Agent 以**树状**实时展示：名称、调用的工具、运行 / 完成 / 出错 / 停滞状态；多级委派可逐层展开。 + +侧栏可**折叠为带角标的竖条**；窄屏（< 1280px）自动降级为**浮层抽屉**，不挤占对话区。它纯前端实现、零新增接口，完全复用现有 SSE 事件流——所以委派树也仍会内联在消息里，侧栏只是把「当前 / 活跃」的总览拎出来常驻。 + +--- + ## 思考、工具调用、以及"该不该信" MateClaw 的聊天 UI 在试着回答一个问题：**AI 刚刚告诉你的事情，该不该信？** 别处的默认答案是"看答案，自己猜"。MateClaw 想做得更好。 diff --git a/mateclaw-server/src/main/resources/docs/zh/desktop.md b/mateclaw-server/src/main/resources/docs/zh/desktop.md index da918b4b..a0dac084 100644 --- a/mateclaw-server/src/main/resources/docs/zh/desktop.md +++ b/mateclaw-server/src/main/resources/docs/zh/desktop.md @@ -50,10 +50,32 @@ - **本地优先的数据** - **动态后端端口** - **UI 热更新**——前端资源可以独立更新，不用重新打包 +- **本地 / 远程双连接模式**——既可用内嵌 JVM 跑本地服务，也可连接集中部署的远程 Server - 跨平台（macOS、Windows、Linux） --- +## 连接模式（本地 / 远程） + +> 适用于「企业多人协作连一台集中部署的 Server」的场景——不必每个人各跑各的本地服务。 + +桌面端有两种连接后端的方式： + +- **本地（`local`）**——启动内嵌的 JRE 21 + 服务 JAR，在本机跑一套完整后端（默认、开箱即用）。 +- **远程（`remote`）**——不启本地服务，直接连你集中部署的远程 Server，所有 API / SSE 都指向它。 + +**首启连接选择器。** 第一次启动（还没选过模式）会弹出连接选择界面让你选模式；选「远程」时填服务器地址，地址会被规范化（自动补 `https://`、去尾斜杠、校验 http(s) 合法性）。选择会记住，之后直接进入。 + +**多服务器与切换。** 连接成功的远程服务器记入「最近使用」列表（按 URL 去重、最多 8 条）。菜单 **「切换服务器」** 随时重新唤出连接选择器，切到另一台 Server。 + +**企业内网自签名证书。** 对用户**显式信任**的 host 放行自签名证书——仅限当前正在连接的远程地址（`trustedCertHosts`），不是通配绕过；未知 host 一律拒绝。适配内网部署常见的自签名证书。 + +**健康检查。** 远程模式以较短超时（约 15s）快速探活（服务端应已就绪），失败给出明确反馈；本地模式等待内嵌后端拉起。 + +连接选择持久化在用户目录下的 `connection.json`（见下方「数据存储」）。 + +--- + ## 支持的平台 | 平台 | 架构 | 状态 | diff --git a/mateclaw-server/src/main/resources/docs/zh/operational-export.md b/mateclaw-server/src/main/resources/docs/zh/operational-export.md new file mode 100644 index 00000000..2ff9ad81 --- /dev/null +++ b/mateclaw-server/src/main/resources/docs/zh/operational-export.md @@ -0,0 +1,77 @@ +# 运营数据导出 + +把一份跨域的运营数据报告一次性导出成 Excel(`.xlsx` 打包为 `.zip`),供运营、审计、对账离线使用。两种入口:**Dashboard 一键导出**(图形界面)和**命令行导出**(无 UI、可 `docker exec`)。 + +> 仅**全局管理员**可用。报告含全工作区的会话内容、Token 用量、审计记录等敏感数据。 + +## 报告包含的 9 张表 + +| # | 表 | 内容 | +|---|---|---| +| 1 | 概览汇总 | 区间 KPI、系统快照、7 天趋势、周期对比、模型明细、Agent 活跃 Top 10 | +| 2 | Token 用量 | 按天 × `runtime_provider` 拆分,含平均 Token/对话 | +| 3 | 技能统计 | 技能清单 + 调用次数、最近调用时间、绑定 Agent | +| 4 | 用户统计 | 按(工作区, 用户)聚合的 Token、时长、最近活跃 | +| 5 | 用户对话 | 用户—助手消息配对的明细行 | +| 6 | 安全与审计 | 跨 6 个来源的统一视图(Guard 规则、审计日志、审批、授权、配置、业务审计事件) | +| 7 | 渠道统计 | 每渠道的对话数、Token、去重用户 | +| 8 | 模型配置 | 已启用 + 已配置 API Key 的模型及参数 | +| 9 | 定时任务 | 执行记录,含时长与 Token 用量 | + +## 入口一:Dashboard 一键导出 + +1. 进入**仪表盘**,右上角(数据库标签旁)点「**导出运营数据**」(仅全局管理员可见)。 +2. 在弹窗里选**时间范围**——可点快捷「近 7 / 30 / 90 天」,或自定义;**最长 90 天**,不可选未来日期。 +3. 点「**生成报告**」——圆形进度环显示 9 步进度(概览 → … → 定时任务)。 +4. 完成后出现「报告已就绪」,点「**下载**」拿到 `ops_data_<起>_<止>.zip`。 + +**关于安全与生命周期:** + +- 生成 / 进度 / 下载三个端点都由 `@RequireGlobalAdmin` 鉴权——非管理员调用返回 403。 +- 一次只允许一个生成任务(并发返回 409 忙碌),前端 5 分钟死线。 +- 下载用一次性令牌,**原子单次有效**——同一令牌第二次下载返回 410。 +- 生成文件在 **24 小时后或下载后**自动清理。 + +## 入口二:命令行导出 + +适合「大范围、无超时、脚本化、`docker exec`」的场景。新增了项目级 CLI 框架,导出命令为 `--cli.command=export`: + +```bash +# 本地 jar +java -jar app.jar --cli.command=export \ + --cli.start=2026-01-01 --cli.end=2026-06-30 > report.zip + +# 容器内 +docker exec <容器名> java -jar /app/app.jar --cli.command=export \ + --cli.start=2026-01-01 --cli.end=2026-06-30 > report.zip + +# 模拟运行(不实际生成) +java -jar app.jar --cli.command=export --cli.start=... --cli.end=... --cli.dry-run + +# 查看所有命令 +java -jar app.jar --cli.command=help +``` + +| 参数 | 必填 | 说明 | +|---|---|---| +| `--cli.command=export` | 是 | 执行导出命令 | +| `--cli.start=YYYY-MM-DD` | 是 | 开始日期(含) | +| `--cli.end=YYYY-MM-DD` | 是 | 结束日期(含) | +| `--cli.dry-run` | 否 | 模拟运行,不实际生成 | + +要点: + +- ZIP 字节直接写入 **stdout**(用 `> report.zip` 重定向),诊断信息走 **stderr**,所以重定向得到的是干净的二进制。 +- 后端入口**无 90 天上限、无超时**,适合大范围离线导出。 +- CLI 仅运维侧可达(本地 / `docker exec`),**不经 HTTP**、不绕过管理员鉴权。 +- 正常 web 启动(没有 `--cli.command`)时 CLI 保持静默,不影响服务启动。 + +## 备注 + +- Excel 中 19 位雪花 ID 以**文本**写出,避免被 Excel 数值精度(2^53)截断、显示成科学计数法。 +- 报告内容随数据增长而变大;命令行导出大范围时建议直接重定向到文件而非管道给其它程序。 + +## 关联 + +- [Backstage 运行时控制台](./backstage) —— 看实时运行的 Agent / 子 Agent +- [安全与审批](./security) —— Tool Guard 与审计日志(Sheet 6 的来源之一) diff --git a/mateclaw-server/src/main/resources/docs/zh/webchat.md b/mateclaw-server/src/main/resources/docs/zh/webchat.md index 0e484171..b0d57ec1 100644 --- a/mateclaw-server/src/main/resources/docs/zh/webchat.md +++ b/mateclaw-server/src/main/resources/docs/zh/webchat.md @@ -77,6 +77,8 @@ init({ apiKey: 'your-channel-api-key', server: 'https://<你的部署地址>' }) | DELETE | `/sessions` | + visitorToken | 删除 | | POST | `/sessions/stop` | + visitorToken | 停止进行中的流 | | POST | `/sessions/regenerate` | + visitorToken | 重新生成最后一条助手回复 | +| POST | `/sessions/approve` | + visitorToken | 批准挂起的工具审批并重放(SSE) | +| POST | `/sessions/deny` | + visitorToken | 拒绝挂起的工具审批(同步 JSON) | | GET | `/sessions/messages` | + visitorToken | 消息列表(支持分页) | | POST | `/upload` | + visitorToken | 上传附件(拿 fileId) | | GET | `/files` | + visitorToken | 下载文件(上传的或 Agent 生成的) | @@ -191,6 +193,31 @@ SDK 里展示"AI 正在打字..."气泡、工具执行徽章("正在搜索...") `/sessions` 返回的每个会话含:`sessionId`、`title`、`lastActiveTime`、`messageCount`、`pinned`、`archived`、`streamStatus`(`running` / `idle`)。 +## 工具审批 resolve(API-Key 渠道) + +WebChat 绑定的 Agent 一旦调用受 [Tool Guard](./security) 保护的工具,这一轮会**挂起等待审批**。访客侧可以在会话内直接批准或拒绝,不必等它超时。 + +- **批准** `POST /sessions/approve` —— 带 `sessionId` + `pendingId`。鉴权复用 visitorToken + 会话归属;`pendingId` 会**严格校验属于本会话**(否则 404),杜绝跨访客越权。批准后**重放**被挂起的工具调用,以 SSE 续流。 +- **拒绝** `POST /sessions/deny` —— 带 `sessionId` + `pendingId`,返回同步 JSON,无需重放。 + +两者都会广播 `tool_approval_resolved` SSE 事件(见上方[可选的实时进度事件](#可选的实时进度事件)),让 SDK / 前端实时清掉审批横幅。 + +> 审批是否会出现,取决于该 Agent 绑定的 Tool Guard 规则是否对某个工具设了 `require_approval`。`pendingId` 从 `tool_approval_requested` 事件里拿。 + +```bash +# 批准(SSE 续流) +curl -N -X POST "https://mate.example.com/api/v1/channels/webchat/sessions/approve" \ + -H "X-MC-Key: " -H "X-Visitor-Token: " \ + -H "Content-Type: application/json" \ + -d '{"sessionId":"s1","pendingId":""}' + +# 拒绝(同步 JSON) +curl -X POST "https://mate.example.com/api/v1/channels/webchat/sessions/deny" \ + -H "X-MC-Key: " -H "X-Visitor-Token: " \ + -H "Content-Type: application/json" \ + -d '{"sessionId":"s1","pendingId":""}' +``` + ## visitorToken 撤销(管理员) 某个 visitor 滥用?管理员调: diff --git a/mateclaw-server/src/main/resources/docs/zh/workflow.md b/mateclaw-server/src/main/resources/docs/zh/workflow.md index 382db51b..71f0e5ec 100644 --- a/mateclaw-server/src/main/resources/docs/zh/workflow.md +++ b/mateclaw-server/src/main/resources/docs/zh/workflow.md @@ -98,6 +98,12 @@ v0 = internal alpha。**7 种 step mode + 6 种 trigger pattern**。`loop` / `in > **不在 v1.3.0 里**：`loop`（迭代 N 次或对数组逐项处理）、`invoke_skill`（直接调用 skill 不经过员工）。等用户反馈再加。 +> **`await_approval` 的渠道通知（1.7.0 起真正生效）**：`approverChannels[]` 的每个元素是 +> - `"channelType"`（如 `"web"`）—— **不主动推送**，运营到管理端 resolve； +> - `"channelType:targetId"`（如 `"feishu:oc_xxx"`、`"wecom:xxx"`）—— **推送审批通知**到该目标（飞书/企微群）。 +> +> 审批通过后工作流**从暂停步骤自动恢复**（resolve→resume 桥接）。飞书/企微群里可**直接点卡片按钮批准/拒绝**完成 resolve。详见[安全与审批](./security)。 + ### 表达式：Pebble 子集 工作流**不**用全功能模板引擎——它支持的是 Kestra 同款 Pebble 子集，只够做条件判断和变量引用，不能跑代码。