tianshu-mcp 0.6.6 → 0.6.7

package/CHANGELOG.en.md

@@ -8,6 +8,33 @@ Chinese version: [CHANGELOG.md](CHANGELOG.md)
 
 ---
 
+## [0.6.7] - 2026-09-24
+
+### Added
+
+- **Terminal-state webhook notifications** ([issue #22](https://github.com/lanlan0811/tianshu-mcp/issues/22)): when a task completes, fails or enters `needs_attention`, a JSON body is **asynchronously POSTed** to a configured URL, cutting the babysitting cost of long tasks. See [task notifications](docs/notifications.en.md).
+- **New `notifications.webhook` in the global `config.json`**: `enabled` (default false) / `url` / `timeoutMs` / `maxRetries` / `backoffMs` / `secret` (HMAC-SHA256 signing) / `events`.
+- **`src/tasks/notifier.ts`**: `TaskNotifier` (fire-and-forget, retry + backoff + timeout, warnings only on failure) and the `statusToEvent()` mapping.
+
+### Changed
+
+- `TaskStore`'s constructor gained an **optional** third argument, `notifier`; terminal notifications are dispatched inside `updateStatus`'s write closure **after** `appendEvent` + `writeSnapshot` succeed. Existing `new TaskStore(home, logger)` calls are entirely unaffected.
+- `src/server.ts` assembles the `TaskNotifier` (reading the same `config.json` lazily, so config edits take effect while running).
+
+### Compatibility
+
+- **Off by default**: unset or `enabled:false` sends **no requests at all**, behaving exactly as v0.6.6.
+- **No tool contract, data model or MCP annotation changes**; only a new **optional** config section.
+
+### Notes (disclosed honestly)
+
+- **The hook point is `TaskStore.updateStatus()`** (the single state-transition choke point), **not** `TaskOrchestrator.finish()` — the latter only covers orchestrator-driven ends, while `cancel()`'s queued branch, `initialize()`'s restart archiving, and `shutdownInterrupt()` / `persistInterrupted()` all bypass it.
+- **"Exactly once" dedupes on `taskId + status + finishedAt`; `prev !== status` cannot be used**: several paths **write `meta.status` directly first** and only then call `updateStatus`, at which point `prev` already equals the target state. `finishedAt` is refreshed by `updateStatus` on a terminal write and cleared by `rework`/`continueTask`, so repeated writes for one episode are suppressed while **a new episode after rework notifies again**. Delivery can still repeat across a server restart or a receiver retry, so receivers should dedupe on the same key.
+- **Only true terminal states are pushed by default**: `needs_attention` (terminal) → `needs_human`; `needs_user` (**non-terminal**, restorable via `continue_task`, possibly re-entered) is a separate class that is **off by default** — callers who want it must add it to `events` explicitly (knowing it will repeat). `cancelled` is likewise off by default.
+- **Best-effort, not guaranteed**: sending is fully asynchronous, so a slow or dead endpoint **does not block the state machine**; failures (network error / timeout / non-2xx) are retried `maxRetries` times and then only logged as a single `warn` — they **never change a task's terminal state**.
+- **The body contains local paths**: it includes `projectPath` and absolute paths to acceptance report files; confirm the receiver is trusted before forwarding to a public service.
+- **`enabled=true` without `url` is rejected by the schema** (no silent "enabled but never sends" confusion); `config.json` follows last-known-good, so a broken file only warns and keeps the previous valid config.
+
 ## [0.6.6] - 2026-09-24
 
 ### Added

package/CHANGELOG.md

@@ -7,6 +7,33 @@
 
 ---
 
+## [0.6.7] - 2026-09-24
+
+### 新增
+
+- **任务终态 webhook 通知**（[issue #22](https://github.com/lanlan0811/tianshu-mcp/issues/22)）：任务完成 / 失败 / 进入 `needs_attention` 时向配置的 URL **异步 POST** 一条 JSON，降低长任务盯屏成本。详见 [任务终态通知](docs/notifications.md)。
+- **全局 `config.json` 新增 `notifications.webhook`**：`enabled`（默认 false）/ `url` / `timeoutMs` / `maxRetries` / `backoffMs` / `secret`（HMAC-SHA256 签名）/ `events`。
+- **`src/tasks/notifier.ts`**：`TaskNotifier`（fire-and-forget、重试 + 退避 + 超时、失败仅告警）与 `statusToEvent()` 映射。
+
+### 变更
+
+- `TaskStore` 构造函数新增**可选**第三参 `notifier`；终态通知在 `updateStatus` 写闭包内 `appendEvent` + `writeSnapshot` **成功之后**派发。既有 `new TaskStore(home, logger)` 调用完全不受影响。
+- `src/server.ts` 装配 `TaskNotifier`（惰性读取同一份 `config.json`，故运行中改配置也能生效）。
+
+### 兼容性
+
+- **默认关闭**：不配置或 `enabled:false` 时**完全不发起任何请求**，行为与 v0.6.6 一致。
+- **无工具契约、数据模型或 MCP 注解变更**；仅新增一个**可选**的 config 段。
+
+### 说明（如实披露）
+
+- **钩子点是 `TaskStore.updateStatus()`**（状态跃迁的唯一咽喉），**不是** `TaskOrchestrator.finish()` —— 后者只覆盖编排器主导的结束，`cancel()` 的 queued 分支、`initialize()` 的重启归档、`shutdownInterrupt()` / `persistInterrupted()` 全都绕过它。
+- **「恰好一次」按 `taskId + status + finishedAt` 去重，不能用 `prev !== status`**：多条路径会**先直接改写 `meta.status`** 再调用 `updateStatus`，那时 `prev` 已等于目标状态。`finishedAt` 由 `updateStatus` 在写终态时刷新、并被 `rework`/`continueTask` 清空 —— 故同回合重复写入被抑制，而**返修后的新回合会再次通知**。跨 server 重启或接收端重试仍可能重复送达，建议接收端按同一键幂等。
+- **默认只推真终态**：`needs_attention`（终态）→ `needs_human`；`needs_user`（**非终态**，可被 `continue_task` 恢复、之后可能再次进入）单独成类且**默认不订阅**，需要它的调用方须显式加入 `events`（已知会反复推送）。`cancelled` 同样默认关闭。
+- **尽力投递，不保证送达**：发送全异步，端点慢或挂掉**不阻塞状态机**；失败（网络错误 / 超时 / 非 2xx）重试 `maxRetries` 次后仅记一条 `warn`，**绝不改变任务终态**。
+- **请求体含本地路径**：包含 `projectPath` 与验收报告文件的绝对路径；转发到公网服务前请确认接收端可信。
+- **`enabled=true` 但缺 `url` 会被 schema 拒绝**（禁止「开了却不发」的静默混淆）；`config.json` 走 last-known-good，写坏只告警并沿用上一份有效配置。
+
 ## [0.6.6] - 2026-09-24
 
 ### 新增

package/README.en.md

@@ -51,6 +51,7 @@ Tianshu plays the role of the overall commander; this MCP server is the **schedu
 - **Idempotent retries (issue #15)**: `run_task` / `verify_task` accept an optional `idempotencyKey` — a retry with the same key within the TTL (24 h default) never duplicates a dispatch (the original `taskId` and its current status are returned) or re-runs verification (a running pass answers "in progress", a finished one returns the existing report); the same key with different arguments fails closed. The mapping is persisted in `<data-dir>/idempotency.json` and survives a server restart. See the [v0.5.10 release notes](<docs/release-v0.5.10.en.md>).
 - **Skill self-install (issue #16)**: on startup the **in-package** `skills/tianshu-mcp/` is synced idempotently to `~/.rivet/skills/tianshu-mcp/`. The source is located relative to the package via `import.meta.url` (no cwd content discovery); an install manifest inside the target lets it auto-upgrade **only when the copy is provably untouched**, while **detected local edits or an unknown source are kept with a warning**; overwrites go through an atomic "tmp dir → backup → swap in" path and are governed by `skills.autoInstall` (`true`/`"prompt"`/`false`) and `skills.backupKeep`. See [README §Skill self-install](#skill-self-install).
 - **Scheduling discipline**: per-project serial queue + global concurrency cap (default 2, configurable); even without an idempotency key, `run_task` names the unfinished task in the same workspace so a retry is not mistaken for a fresh dispatch.
+- **Terminal-state notifications (issue #22)**: an optional `notifications.webhook` (global `config.json`) **asynchronously POSTs** a JSON body (with `taskId` / `event` / `status` / timestamp / report paths) to a URL when a task completes, fails or enters `needs_attention`, with optional HMAC-SHA256 signing. **Off by default**, and a failed send only logs — it **never affects the state machine**. Only true terminal states are pushed by default; `needs_user` (non-terminal, can repeat) must be subscribed explicitly. See [task notifications](docs/notifications.en.md).
 - **Optional AI content validation (v0.5.4, off by default)**: validates whether the **content** of an image or page screenshot matches an expectation you declare explicitly. Judgement is fully **delegated to a local command you supply** (the MCP reads, stores, and forwards no keys and ships no model client), it **warns only** by default and can be upgraded to failing per rule, and it debounces with majority sampling plus a task-level cache; split votes or confidence below the threshold yield `uncertain`, which never gates and never triggers rework. Configuration and the command contract are in [visual acceptance](docs/visual-acceptance.en.md).
 - **No key handling**: each agent uses its own login state; this server never stores or forwards any API key. Optional AI content validation adds no credential management either — the judge command manages its own key (see [SECURITY.en.md](SECURITY.en.md)).
 - **Extensible**: a new agent = one profile (data) + (if needed) one adapter file — no changes to the orchestration core.

package/README.md

@@ -51,6 +51,7 @@
 - **幂等重试（issue #15）**：`run_task` / `verify_task` 接受可选 `idempotencyKey`——同一 key 在 TTL（默认 24h）内的重试**不会**重复派单（恒返回原 `taskId` 与当前状态）或重复跑验收（执行中返回进行中提示，已完成直接返回既有报告）；同键异参 fail-closed 报错。映射落盘于 `<数据目录>/idempotency.json`，跨 server 重启仍生效。详见 [v0.5.10 发布说明](<docs/release-v0.5.10.md>)。
 - **技能自检安装（issue #16）**：启动时把**包内** `skills/tianshu-mcp/` 幂等同步到 `~/.rivet/skills/tianshu-mcp/`。源只由 `import.meta.url` 相对包自身定位（无 cwd 内容发现）；目标内含安装清单，据此仅在**可证未被改动**时自动升级，**检出你的本地修改或来源不明一律保留 + 告警**；覆盖走「临时目录 → 备份 → 换入」的原子路径，并按 `skills.autoInstall`（`true`/`"prompt"`/`false`）与 `skills.backupKeep` 治理。详见 [README §技能自检安装](#技能自检安装)。
 - **调度纪律**：每项目串行队列 + 全局并发上限（默认 2，可配）；未传幂等键时，`run_task` 仍会点名同工作区未结束的任务，避免误判为重试。
+- **终态通知（issue #22）**：可选 `notifications.webhook`（全局 `config.json`）—— 任务完成 / 失败 / 进入 `needs_attention` 时向指定 URL **异步 POST** 一条 JSON（含 `taskId` / `event` / `status` / 时间戳 / 报告路径），可选 HMAC-SHA256 签名。**默认关闭**，且发送失败只记日志、**绝不影响状态机**。默认只推真终态；`needs_user`（非终态，可能反复触发）需显式订阅。详见 [任务终态通知](docs/notifications.md)。
 - **可选 AI 内容校验（v0.5.4，默认关闭）**：校验图片或页面截图**内容**是否符合你显式声明的期望描述。判定完全**委托给你自备的本地命令**（MCP 不读取、不存储、不转发任何密钥，也不内置模型客户端），默认**仅告警**、逐规则可升级为致败；采样多数票 + 任务级缓存防抖，票不集中或低于置信度阈值判 `uncertain`（永不阻塞、不触发返修）。配置与命令契约见 [视觉验收](docs/visual-acceptance.md)。
 - **不碰密钥**：各 agent 用自己的登录态；本 server 不保存/转发任何 API key。可选 AI 内容校验同样不引入凭证管理——判定命令自己管密钥（见 [SECURITY.md](SECURITY.md)）。
 - **可扩展**：新 agent = 一个 profile（数据）+（如需）一个 adapter 文件，零改编排核心。

package/dist/config/schema.js

@@ -210,6 +210,44 @@ export const ContinueTaskParamsSchema = z.object({
     message: z.string().min(1, "message 不能为空"),
 });
 /* ---------------- server 配置 config.json ---------------- */
+/**
+ * webhook 通知可订阅的事件类别（按任务**状态语义**归类，而非原始 status 字符串）。
+ *
+ * `needs_human` 与 `needs_user` 刻意分开：前者对应 `needs_attention`（**真终态**，等人工裁决后
+ * 任务就结束了），后者对应 `needs_user`（**非终态** —— 它可被 `continue_task` 恢复到 `queued`，
+ * 之后可能**再次**进入 `needs_user`）。混为一类会让「默认只推真终态」这条约定失效。
+ */
+export const NotificationEventSchema = z.enum([
+    "done",
+    "failed",
+    "needs_human",
+    "needs_user",
+    "cancelled",
+]);
+/**
+ * 默认订阅集：**只含真终态**。
+ * `needs_user` 不是终态，默认关闭；需要它的调用方显式加进 `events`（已知会反复推送）。
+ * `cancelled` 同样默认关闭（多数场景无需被取消任务打扰）。
+ */
+export const NOTIFICATION_EVENTS_DEFAULT = ["done", "failed", "needs_human"];
+export const WebhookConfigSchema = z
+    .object({
+    enabled: z.boolean().default(false),
+    url: z.string().url().optional(),
+    /** 单次请求超时（不阻塞状态机 —— 发送全程异步） */
+    timeoutMs: z.number().int().positive().default(5_000),
+    /** 失败重试次数上限（0 = 不重试）；总尝试次数 = 1 + maxRetries */
+    maxRetries: z.number().int().min(0).max(5).default(2),
+    /** 重试退避基数：第 n 次重试前等待 backoffMs × n（0 = 不退避） */
+    backoffMs: z.number().int().min(0).default(500),
+    /** 配置后对请求体做 HMAC-SHA256 签名，附 `X-Tianshu-Signature: sha256=<hex>` */
+    secret: z.string().optional(),
+    events: z.array(NotificationEventSchema).default(NOTIFICATION_EVENTS_DEFAULT),
+})
+    .refine((v) => !v.enabled || (v.url !== undefined && v.url.length > 0), {
+    message: "notifications.webhook.enabled=true 时必须提供 url",
+    path: ["url"],
+});
 export const ServerConfigSchema = z.object({
     concurrency: z
         .object({
@@ -274,6 +312,20 @@ export const ServerConfigSchema = z.object({
             .default(IDEMPOTENCY_MAX_ENTRIES_DEFAULT),
     })
         .default({}),
+    /**
+     * 任务状态跃迁的通知钩子（issue #22）。
+     *
+     * 放在**全局** `config.json` 而非项目 `acceptance.json`：通知路由是宿主/传输层关注点，
+     * 不是项目验收策略；一个端点通常按 `taskId` 自行分流即可。且状态跃迁的咽喉
+     * （`TaskStore.updateStatus`）只有 `home` / `taskId` / `logger`，无法在每次跃迁时廉价读项目配置。
+     *
+     * **默认关闭**：不配置或 `enabled:false` 时**完全不发起任何请求**。
+     */
+    notifications: z
+        .object({
+        webhook: WebhookConfigSchema.optional(),
+    })
+        .default({}),
 });
 /* ---------------- agent-profiles.json ---------------- */
 export const ExecutableDiscoverySchema = z.object({

package/dist/server.js

@@ -8,6 +8,7 @@ import { resolveDataHome, DataHome } from "./config/store.js";
 import { BUILTIN_PROFILES } from "./agents/builtin.js";
 import { AgentAdapterRegistry } from "./agents/registry.js";
 import { TaskStore } from "./tasks/task-store.js";
+import { TaskNotifier } from "./tasks/notifier.js";
 import { AcceptanceEngine } from "./verify/acceptance.js";
 import { TaskManager } from "./tasks/task-manager.js";
 import { makeBuildCtx } from "./mcp/context.js";
@@ -26,7 +27,10 @@ export async function buildServer(opts = {}) {
     // shutdown 预算（issue #14）：GUI 任务在 server 退出时的停止等待上限，注入 manager 供
     // shutdownInterrupt() 使用；与 profile 的 gui.cancelWaitMs（取消路径）解耦。
     const guiStopWaitMs = cfg.shutdown?.guiStopWaitMs ?? 15_000;
-    const store = new TaskStore(home, logger);
+    // 任务终态通知（issue #22）：配置读同一份 config.json（支持热加载），故用 getter 惰性取，
+    // 运行中改配置也能生效。默认关闭 —— 未配置 webhook 时 notify 是空操作。
+    const notifier = new TaskNotifier(() => dataHome.loadConfig(), logger);
+    const store = new TaskStore(home, logger, notifier);
     const registry = new AgentAdapterRegistry(() => dataHome.loadProfiles(), logger);
     const engine = new AcceptanceEngine(store, logger);
     const manager = new TaskManager(store, dataHome, registry, engine, logger, makeBuildCtx({ store, dataHome }));

package/dist/tasks/notifier.js

@@ -0,0 +1,117 @@
+/**
+ * 任务终态通知（issue #22）。
+ *
+ * 长任务下调用方原先必须一直挂在天枢界面轮询 `query_task`；任务完成/失败/进入 `needs_attention`
+ * 时没有任何主动推送，盯屏成本高。本模块在终态跃迁时向配置的 URL POST 一条 JSON。
+ *
+ * 设计约束（都是 issue 明确要求的）：
+ * - **异步、不阻塞状态机**：`notify()` 立即返回，发送在后台进行。
+ * - **失败不影响任务**：任何异常只记 `warn`，绝不外抛、绝不改变状态机。
+ * - **默认关闭**：未配置 / `enabled:false` / 事件不在订阅集 → **完全不发起请求**。
+ * - 重试 + 超时控制：总尝试 `1 + maxRetries` 次，退避 `backoffMs × 第几次`。
+ *
+ * 「恰好一次」的保证方式：按 `taskId + status + finishedAt` 进程内去重。
+ * `finishedAt` 由 `updateStatus` 在写入终态时刷新为当前时刻，并被 `rework` / `continueTask`
+ * 清空 —— 因此**同一回合**的重复写入被抑制，而返修后的**新一回合同样状态会再次通知**。
+ * 不能改用 `prev !== status` 作为门条件：多条路径（cancel 的 queued 分支、shutdownInterrupt）
+ * 会先直接改写 `meta.status` 再调用 `updateStatus`，那时 `prev` 已等于目标状态。
+ */
+import { createHmac } from "node:crypto";
+/**
+ * 任务状态 → 通知事件类别；非终态/不产生通知的状态返回 undefined。
+ *
+ * `needs_attention`（真终态）→ `needs_human`；`needs_user`（**非终态**，可被 continue 恢复、
+ * 之后可能再次进入）→ 单独的 `needs_user` 类别，默认不在订阅集里（见 schema）。
+ * 两者分开是刻意的：混为一类会让「默认只推真终态」失效。
+ */
+export function statusToEvent(status) {
+    switch (status) {
+        case "succeeded":
+            return "done";
+        case "failed":
+            return "failed";
+        case "needs_attention":
+            return "needs_human";
+        case "needs_user":
+            return "needs_user";
+        case "cancelled":
+        case "interrupted":
+            return "cancelled";
+        default:
+            return undefined;
+    }
+}
+const sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+export class TaskNotifier {
+    getConfig;
+    logger;
+    /** 已通知过的 `taskId:status:finishedAt`（进程内；重启后按新回合重新通知，如实） */
+    sent = new Set();
+    constructor(getConfig, logger) {
+        this.getConfig = getConfig;
+        this.logger = logger;
+    }
+    /** fire-and-forget：立即返回，发送与重试都在后台；绝不外抛 */
+    notify(payload) {
+        const key = `${payload.taskId}:${payload.status}:${payload.finishedAt ?? ""}`;
+        if (this.sent.has(key))
+            return;
+        this.sent.add(key);
+        void this.send(payload).catch((e) => {
+            // send 内部已吞掉异常，这里是最后一道保险：通知绝不允许影响任务
+            this.logger.warn(`任务 ${payload.taskId} 通知发送出现未预期异常：${e instanceof Error ? e.message : String(e)}`);
+        });
+    }
+    async send(payload) {
+        let webhook;
+        try {
+            webhook = (await this.getConfig()).notifications?.webhook;
+        }
+        catch (e) {
+            this.logger.warn(`读取通知配置失败，跳过任务 ${payload.taskId} 的通知：${e instanceof Error ? e.message : String(e)}`);
+            return;
+        }
+        // 默认关闭：未配置 / 未启用 / 无 url / 事件未订阅 → 不发起任何请求
+        if (!webhook?.enabled || !webhook.url)
+            return;
+        if (!webhook.events.includes(payload.event))
+            return;
+        const body = JSON.stringify(payload);
+        const headers = {
+            "content-type": "application/json",
+            "x-tianshu-event": payload.event,
+        };
+        if (webhook.secret) {
+            headers["x-tianshu-signature"] =
+                `sha256=${createHmac("sha256", webhook.secret).update(body, "utf8").digest("hex")}`;
+        }
+        const attempts = 1 + webhook.maxRetries;
+        let lastError = "未知原因";
+        for (let attempt = 1; attempt <= attempts; attempt++) {
+            try {
+                const res = await fetch(webhook.url, {
+                    method: "POST",
+                    headers,
+                    body,
+                    // 与 visual 服务同一约定：不自动跟随重定向，超时用 AbortSignal.timeout
+                    redirect: "manual",
+                    signal: AbortSignal.timeout(webhook.timeoutMs),
+                });
+                if (res.ok) {
+                    this.logger.info(`任务 ${payload.taskId} 通知已送达（${payload.event}，HTTP ${res.status}${attempt > 1 ? `，第 ${attempt} 次尝试` : ""}）`);
+                    return;
+                }
+                lastError = `HTTP ${res.status}`;
+            }
+            catch (e) {
+                lastError = e instanceof Error ? e.message : String(e);
+            }
+            if (attempt < attempts && webhook.backoffMs > 0) {
+                // eslint-disable-next-line no-await-in-loop
+                await sleep(webhook.backoffMs * attempt);
+            }
+        }
+        // 尽最大努力通知即止：失败不影响任务本体，也不重排状态机
+        this.logger.warn(`任务 ${payload.taskId} 通知发送失败（${payload.event}，已尝试 ${attempts} 次）：${lastError}`);
+    }
+}

package/dist/tasks/task-store.js

@@ -7,6 +7,7 @@ import path from "node:path";
 import { TERMINAL_STATUSES, ACTIVE_STATUSES, } from "./task.js";
 import { appendLine, exists, mkdirp, readDirSafe, readJsonSafe, readTextSafe, readTextTail, writeJsonAtomic, writeTextAtomic, } from "../util/fs.js";
 import { isAgentEventName } from "../agents/agent-events.js";
+import { statusToEvent } from "./notifier.js";
 import { nowIso } from "../util/id.js";
 import { reportToJsonable, reportToMd } from "../verify/report.js";
 import { dryRunReportToJsonable, renderDryRunReportMd, } from "../verify/dry-run.js";
@@ -26,10 +27,17 @@ const STATUS_EVENT_MAP = {
 export class TaskStore {
     home;
     logger;
+    notifier;
     statusWriteTails = new Map();
-    constructor(home, logger) {
+    constructor(home, logger, 
+    /**
+     * 任务终态通知器（issue #22，**可选**）。默认不传 = 与引入本能力前完全一致（测试大量
+     * 直接 `new TaskStore(home, logger)`，故必须保持可选）。
+     */
+    notifier) {
         this.home = home;
         this.logger = logger;
+        this.notifier = notifier;
     }
     dir(taskId) {
         return path.join(this.home, "tasks", taskId);
@@ -161,6 +169,9 @@ export class TaskStore {
             await this.appendEvent(taskId, name, status, detail);
             await this.writeSnapshot(meta);
             this.logger.debug(`任务 ${taskId}: ${prev} → ${status}${detail ? ` (${detail})` : ""}`);
+            // issue #22：终态通知。**在 appendEvent + writeSnapshot 成功之后**才发——先保证
+            // 本地事实已落盘，再对外通知；notify 是 fire-and-forget，不阻塞状态机写入链。
+            this.notifyTerminal(meta, status);
         })();
         this.statusWriteTails.set(taskId, write);
         try {
@@ -171,6 +182,28 @@ export class TaskStore {
                 this.statusWriteTails.delete(taskId);
         }
     }
+    /** 终态跃迁的通知派发（issue #22）；未传 notifier 或非通知状态时是空操作 */
+    notifyTerminal(meta, status) {
+        if (!this.notifier)
+            return;
+        const event = statusToEvent(status);
+        if (!event)
+            return;
+        this.notifier.notify({
+            taskId: meta.taskId,
+            event,
+            status,
+            ts: nowIso(),
+            finishedAt: meta.finishedAt,
+            agentId: meta.agentId,
+            projectPath: meta.projectPath,
+            round: meta.roundsUsed,
+            reportRound: meta.reportRound,
+            message: meta.lastMessage,
+            reportMd: meta.reportMd,
+            reportJson: meta.reportJson,
+        });
+    }
     async addNote(meta, detail) {
         meta.updatedAt = nowIso();
         await this.appendEvent(meta.taskId, "note", meta.status, detail);

package/dist/version.generated.js

@@ -4,4 +4,4 @@
  * 本文件由 scripts/sync-version.mjs 在每次 build 前重新生成。
  */
 // generated: 勿手改 —— 运行 `npm run build` 自动同步
-export const MCP_SERVER_VERSION = "0.6.6";
+export const MCP_SERVER_VERSION = "0.6.7";

package/docs/notifications.en.md

@@ -0,0 +1,127 @@
+# Task notification (webhook, issue #22)
+
+Chinese version: [notifications.md](notifications.md)
+
+For long tasks the caller previously had to keep polling `query_task` from the Tianshu UI; nothing was
+pushed when a task completed, failed or entered `needs_attention`, so babysitting was expensive. This
+capability POSTs a JSON body to a configured URL on state transitions.
+
+The receiver is yours to implement — a Feishu / DingTalk bot or a small self-hosted service both work.
+
+## 1. Configuration
+
+It lives in the **global** `config.json` (in the data home, `~/.tianshu-mcp/config.json` by default,
+overridable with `TIANSHU_MCP_HOME`):
+
+```jsonc
+{
+  "notifications": {
+    "webhook": {
+      "enabled": true,                 // default false; unset or false sends **no requests at all**
+      "url": "https://example.com/hook", // required when enabled=true (the schema rejects its absence)
+      "timeoutMs": 5000,               // per-request timeout, default 5s
+      "maxRetries": 2,                 // retry cap, default 2 (total attempts = 1 + maxRetries)
+      "backoffMs": 500,                // backoff base: waits backoffMs × n before retry n, default 500
+      "secret": "your-signing-key",    // optional; adds an HMAC-SHA256 signature over the body
+      "events": ["done", "failed", "needs_human"] // optional; defaults below
+    }
+  }
+}
+```
+
+**Why the global config rather than a project `acceptance.json`**: notification routing is a
+**host / transport** concern, not project acceptance policy; one endpoint normally demultiplexes by the
+`taskId` in the body. Also, the state-transition choke point (`TaskStore.updateStatus`) only has the data
+home, taskId and logger, so it cannot cheaply read project config on every transition.
+
+**When the config is broken**: `config.json` follows a last-known-good policy — a validation failure logs
+a warning and keeps the previous valid config, so one bad notification line cannot stop the server from
+starting.
+
+## 2. Event classes and the default subscription
+
+| Event | Task status | Subscribed by default |
+|---|---|---|
+| `done` | `succeeded` | ✅ |
+| `failed` | `failed` | ✅ |
+| `needs_human` | `needs_attention` (**terminal** — the task ends once a human rules) | ✅ |
+| `needs_user` | `needs_user` (**non-terminal** — `continue_task` can restore it to `queued`, and it may enter `needs_user` again) | ❌ opt in |
+| `cancelled` | `cancelled` / `interrupted` | ❌ opt in |
+
+**Only true terminal states are pushed by default.** `needs_user` and `needs_attention` are deliberately
+separate classes: the former is non-terminal and can fire repeatedly in one long task, so enabling it by
+default would be noise; callers who want it can add it to `events` (knowing it will repeat).
+
+## 3. Request body
+
+```jsonc
+{
+  "taskId": "tsk_xxx",
+  "event": "done",                 // done | failed | needs_human | needs_user | cancelled
+  "status": "succeeded",           // raw task status (finer than event; lets receivers demultiplex)
+  "ts": "2026-09-24T12:00:00.000Z",// when the event happened
+  "finishedAt": "2026-09-24T12:00:00.000Z",
+  "agentId": "codex",
+  "projectPath": "D:/proj",
+  "round": 1,                      // rounds used
+  "reportRound": 0,                // latest acceptance report round (if any)
+  "message": "验收通过。",          // terminal message
+  "reportMd": "...report-0.md",    // acceptance report paths (if any)
+  "reportJson": "...report-0.json"
+}
+```
+
+Headers:
+
+| Header | Notes |
+|---|---|
+| `content-type` | `application/json` |
+| `X-Tianshu-Event` | The event class (same as the body's `event`, so receivers can route without parsing) |
+| `X-Tianshu-Signature` | Only when `secret` is configured: `sha256=<hex>`, HMAC-SHA256 over the **raw request body string** |
+
+## 4. Receiver guidance
+
+**Verify the signature** (do this whenever `secret` is set, to prevent forged notifications):
+
+```js
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+function verify(rawBody, signatureHeader, secret) {
+  const expected = `sha256=${createHmac("sha256", secret).update(rawBody, "utf8").digest("hex")}`;
+  const a = Buffer.from(expected);
+  const b = Buffer.from(signatureHeader ?? "");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+```
+
+Use the **raw body string** (never a re-`JSON.stringify`'d object — key order changes and the signature
+will not verify).
+
+**Feishu custom bot**: its webhook expects its own envelope
+(`{"msg_type":"text","content":{"text":"…"}}`), which differs from this MCP's body. Two options:
+
+1. Run a small forwarding service: receive the MCP notification → verify the signature → reshape into
+   the Feishu envelope and forward;
+2. Use a gateway / serverless function that rewrites the body the same way.
+
+**DingTalk is analogous** (`{"msgtype":"text","text":{"content":"…"}}`, usually with extra signing params).
+
+**Idempotency advice**: dedupe on the receiver by `taskId + status + finishedAt` (the MCP already dedupes
+on that key in-process, but delivery can still repeat across restarts or retries — see below).
+
+## 5. Delivery semantics (disclosed honestly)
+
+- **Best-effort, not delivery-guaranteed**: notifications are an observability capability, not a delivery
+  guarantee. A failed send only writes a `warn` log — it never reorders the state machine, changes a task's
+  terminal state, or blocks any call.
+- **Non-blocking**: sending is fully asynchronous (fire-and-forget). A slow or dead endpoint **will not**
+  slow the task down.
+- **Retries**: total attempts `1 + maxRetries`; network errors, timeouts and non-2xx are all retried;
+  backoff is `backoffMs × attempt number`. After exhausting them, one `warn` is logged.
+- **What "exactly once" covers**: the MCP dedupes on `taskId + status + finishedAt` **in-process** — repeated
+  status writes for the same episode notify once, while a new episode after rework (a changed `finishedAt`)
+  notifies again. Across a server restart or a receiver retry, delivery can still repeat, so receivers
+  should be idempotent.
+- **Redirects are not followed**: `redirect: "manual"` — the endpoint should return 2xx directly.
+- **The body may contain project paths**: it includes `projectPath` and local absolute paths to report
+  files. Make sure the receiver is trusted (especially when forwarding notifications to a public service).

package/docs/notifications.md

@@ -0,0 +1,118 @@
+# 任务终态通知（webhook，issue #22）
+
+英文版：[notifications.en.md](notifications.en.md)
+
+长任务下调用方原先必须一直挂在天枢界面轮询 `query_task`；任务完成 / 失败 / 进入 `needs_attention`
+时没有任何主动推送，盯屏成本高。本能力在状态跃迁时向配置的 URL POST 一条 JSON。
+
+接收端由使用者自行实现 —— 飞书 / 钉钉机器人、自建小服务均可。
+
+## 一、配置
+
+放在**全局** `config.json`（数据目录，默认 `~/.tianshu-mcp/config.json`，可用环境变量
+`TIANSHU_MCP_HOME` 覆盖）：
+
+```jsonc
+{
+  "notifications": {
+    "webhook": {
+      "enabled": true,                 // 默认 false；不配置或 false 时**完全不发请求**
+      "url": "https://example.com/hook", // enabled=true 时必填（缺它会被 schema 拒绝）
+      "timeoutMs": 5000,               // 单次请求超时，默认 5s
+      "maxRetries": 2,                 // 失败重试次数上限，默认 2（总尝试 = 1 + maxRetries）
+      "backoffMs": 500,                // 退避基数：第 n 次重试前等 backoffMs × n，默认 500
+      "secret": "your-signing-key",    // 可选；配置后对请求体做 HMAC-SHA256 签名
+      "events": ["done", "failed", "needs_human"] // 可选；默认见下
+    }
+  }
+}
+```
+
+**为什么放在全局 config 而不是项目 `acceptance.json`**：通知路由是**宿主 / 传输层**的关注点，
+不是项目验收策略；一个端点通常按请求体里的 `taskId` 自行分流即可。而且状态跃迁的咽喉
+（`TaskStore.updateStatus`）只有数据目录 / taskId / logger，无法在每次跃迁时廉价读取项目配置。
+
+**配置写坏时**：`config.json` 走「last-known-good」策略 —— 校验失败会告警并沿用上一份有效配置，
+不会因为写错一行通知配置就让整个 server 起不来。
+
+## 二、事件类别与默认订阅集
+
+| 事件 | 对应任务状态 | 默认订阅 |
+|---|---|---|
+| `done` | `succeeded` | ✅ |
+| `failed` | `failed` | ✅ |
+| `needs_human` | `needs_attention`（**真终态**，等人工裁决后任务即结束） | ✅ |
+| `needs_user` | `needs_user`（**非终态** —— 可被 `continue_task` 恢复到 `queued`，之后可能**再次**进入） | ❌ 需显式开启 |
+| `cancelled` | `cancelled` / `interrupted` | ❌ 需显式开启 |
+
+**默认只推真终态**。`needs_user` 与 `needs_attention` 刻意分成两个类别：前者不是终态，
+一次长任务里可能反复触发，默认打开会变成打扰；需要它的调用方把它加进 `events` 即可（已知会重复推送）。
+
+## 三、请求体
+
+```jsonc
+{
+  "taskId": "tsk_xxx",
+  "event": "done",                 // done | failed | needs_human | needs_user | cancelled
+  "status": "succeeded",           // 原始任务状态（比 event 更细，便于接收端自行分流）
+  "ts": "2026-09-24T12:00:00.000Z",// 事件发生时刻
+  "finishedAt": "2026-09-24T12:00:00.000Z",
+  "agentId": "codex",
+  "projectPath": "D:/proj",
+  "round": 1,                      // 已用轮次
+  "reportRound": 0,                // 最新验收报告轮次（若有）
+  "message": "验收通过。",          // 终态文案
+  "reportMd": "...report-0.md",    // 验收报告路径（若有）
+  "reportJson": "...report-0.json"
+}
+```
+
+请求头：
+
+| 头 | 说明 |
+|---|---|
+| `content-type` | `application/json` |
+| `X-Tianshu-Event` | 事件类别（与 body 的 `event` 一致，便于接收端免解析分流） |
+| `X-Tianshu-Signature` | 仅在配置了 `secret` 时出现：`sha256=<hex>`，对**原始请求体字符串**做 HMAC-SHA256 |
+
+## 四、接收端实现建议
+
+**校验签名**（配了 `secret` 时务必做，防止伪造通知）：
+
+```js
+import { createHmac, timingSafeEqual } from "node:crypto";
+
+function verify(rawBody, signatureHeader, secret) {
+  const expected = `sha256=${createHmac("sha256", secret).update(rawBody, "utf8").digest("hex")}`;
+  const a = Buffer.from(expected);
+  const b = Buffer.from(signatureHeader ?? "");
+  return a.length === b.length && timingSafeEqual(a, b);
+}
+```
+
+注意要拿**原始 body 字符串**（不是重新 `JSON.stringify` 的对象 —— 键顺序会变，签不上）。
+
+**飞书自定义机器人**：其 webhook 要求特定报文格式（`{"msg_type":"text","content":{"text":"…"}}`），
+与本 MCP 的请求体不同。两种接法：
+
+1. 自建一个转发小服务：收本 MCP 的通知 → 校验签名 → 拼成飞书格式再转发；
+2. 用一个能改写报文的网关 / Serverless 函数做同样的事。
+
+**钉钉同理**（要求 `{"msgtype":"text","text":{"content":"…"}}`，且通常需要加签参数）。
+
+**幂等建议**：接收端按 `taskId + status + finishedAt` 去重（MCP 侧已按同一键在进程内去重，
+但跨重启或重试仍可能重复送达 —— 见下节）。
+
+## 五、交付语义（如实披露）
+
+- **尽力投递，不保证送达**：通知是观测能力，不是交付保证。发送失败只写 `warn` 日志，
+  **不重排状态机、不改任务终态、不阻塞任何调用**。
+- **不阻塞**：发送全程异步（fire-and-forget）。端点慢或挂掉**不会**拖慢任务。
+- **重试**：总尝试 `1 + maxRetries` 次；网络错误、超时、非 2xx 都重试；退避 `backoffMs × 第几次`。
+  全部失败后仅记一条 `warn`。
+- **恰好一次的范围**：MCP 侧按 `taskId + status + finishedAt` 在**进程内**去重 ——
+  同一回合的重复状态写入只通知一次；返修后的新回合（`finishedAt` 变化）会**再次**通知。
+  跨 server 重启或接收端重试仍可能重复送达，故建议接收端自行幂等。
+- **不跟随重定向**：`redirect: "manual"`，端点请直接返回 2xx。
+- **正文可能含项目路径**：请求体含 `projectPath` 与报告文件的本地绝对路径。请确认接收端可信
+  （尤其是把通知转发到公网服务时）。

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "tianshu-mcp",
-  "version": "0.6.6",
+  "version": "0.6.7",
   "description": "天枢 × AI-Agent 编排 MCP server —— 驱动 Codex、TraeWork、ZCode、Kimi Code 与 Qoder CN 完成项目开发、验收、失败返修与再验收闭环。",
   "type": "module",
   "license": "Apache-2.0",
@@ -25,6 +25,8 @@
     "docs/repair-directives.en.md",
     "docs/dry-run.md",
     "docs/dry-run.en.md",
+    "docs/notifications.md",
+    "docs/notifications.en.md",
     "docs/visual-acceptance.md",
     "docs/visual-acceptance.en.md",
     "docs/visual-validation.md",