feat(integrations): 微信里发一句话，变成一条任务或知识

一条通道一张令牌，机器人把消息 POST 到 /integrations/clawbot/{token}，正文按前缀落到任务或知识草稿：没有前缀就是任务，「知识：」「笔记：」记成知识，「帮助」只回用法。首行当标题、其余当正文，`#标签` 摘出来挂到事项上。同一个 msg_id 只处理一次——微信会重推，重推不能变成两条任务。为什么不塞进 system_setting 的 JSON：一个工作区可能挂多个通道，还得能单独停用。令牌库里只存 sha256，只在创建/重新生成时显示一次；收消息时还不知道是哪个工作区，所以 bot_channel 的 RLS 额外放行 token_hash = current_setting('app.bot_token_hash')，读到通道再 bind_tenant 进上下文，按通道创建者记账。 - 后端：models_integrations.py（bot_channel / bot_message）、迁移 0012（RLS）、 api/integrations.py（收消息 + 管理接口）、错误码 9002/9003 - Web：/w/:wsId/integrations「接入」页——建通道、复制回调地址与令牌、最近消息、停用/换令牌/删除，只有 owner/admin 能改 - 测试：test_clawbot.py 10 例；web/e2e/integrations.mjs 7 项（冒充 clawbot 真推一条）验证：pytest 150 passed，ruff check/format 全绿，tsc 0，vite build 通过，e2e 7 项全绿。
2026-11-05 22:04:34 +08:00
parent 33a3fc03e0
commit 90b99f8253
16 changed files with 1606 additions and 4 deletions
@@ -0,0 +1,562 @@
+"""外部接入：微信（clawbot）发来的消息变成任务 / 知识。
+
+## 一条消息是怎么变成事项的
+
+微信里发一句话给机器人，clawbot 把消息 POST 到
+
+    POST /api/v1/integrations/clawbot/{token}
+
+令牌在 URL 里，**不带登录态**：机器人不会登我们的账号，它只会照着配置好的
+地址发。令牌是 32 字节随机串，库里只存 sha256。
+
+正文按前缀决定去哪个池子：
+
+    知识：xxx / 笔记：xxx / note: xxx   →  知识草稿
+    任务：xxx / todo: xxx               →  任务（默认也是任务）
+    ?、帮助、help                        →  回一段用法说明
+
+首行是标题，其余行是正文。首行里的 `#标签` 会被摘出来挂到事项上
+（标签是知识的主要检索入口，手机上敲#比打开网页加标签省事）。
+
+## 为什么每条消息都留痕
+
+微信会重推（网络抖动、机器人重启）。没有留痕就只能靠猜"那条任务到底进没进"。
+`bot_message.external_id` 上有个部分唯一索引：同一个外部消息 id 第二次到达时
+直接回上次的答案，不会变成两条任务。
+
+## 安全边界
+
+- 令牌错 → 9002（对外一律"通道不存在"，不区分"错令牌"和"这个工作区没接"）。
+- 通道被停用 → 9003。
+- 消息里不认人：机器人只知道"这是这个工作区的一条消息"，落库按通道创建者记账，
+  不会因为消息内容去猜是谁发的。
+"""
+
+from __future__ import annotations
+
+import hashlib
+import secrets
+import uuid
+from datetime import datetime, timezone
+from typing import Annotated, Any
+
+from fastapi import APIRouter, Body, Query, Request
+from fastapi.responses import PlainTextResponse
+from sqlalchemy import select
+from sqlalchemy.exc import IntegrityError
+
+from ..db import bind_tenant
+from ..deps import AdminDep, SessionDep
+from ..errors import AppError, ErrorCode
+from ..models import Member, Workspace
+from ..models_integrations import BotChannel, BotMessage
+from ..models_knowledge import KnowledgeDoc
+from ..models_task import Item
+from ..schemas import ok
+from .items import _log, _set_tags
+
+webhook_router = APIRouter(prefix="/integrations", tags=["外部接入"])
+admin_router = APIRouter(prefix="/workspaces", tags=["外部接入"])
+
+# 标题在 item.title 上是 varchar(200)，留点余量给"…"之类的后缀。
+MAX_TITLE = 180
+MAX_BODY = 20000
+
+KNOWLEDGE_PREFIXES = ("知识", "笔记", "note", "knowledge", "kb")
+TASK_PREFIXES = ("任务", "待办", "todo", "task")
+HELP_PREFIXES = ("?", "？", "帮助", "help", "用法")
+
+HELP_TEXT = (
+    "发什么都能用，写法：\n"
+    "· 直接说　→ 记成任务\n"
+    "· 知识：内容　→ 记成知识草稿（也可以写「笔记：」）\n"
+    "· 任务：内容　→ 明确记成任务\n"
+    "首行当标题，后面几行当正文；标题里带 #标签 会自动加上。"
+)
+
+
+def hash_token(token: str) -> str:
+    return hashlib.sha256(token.encode("utf-8")).hexdigest()
+
+
+def new_token() -> str:
+    return secrets.token_urlsafe(32)
+
+
+def _pick(data: dict[str, Any], *keys: str) -> str | None:
+    """从任意形状的 payload 里挖字段（clawbot 的消息壳子没定死，宽松一点）。"""
+    for key in keys:
+        value = data.get(key)
+        if isinstance(value, str) and value.strip():
+            return value
+        if isinstance(value, dict):
+            nested = _pick(value, "text", "content", "body", "message")
+            if nested:
+                return nested
+    return None
+
+
+def extract_text(payload: dict[str, Any]) -> str:
+    text = _pick(
+        payload,
+        "text",
+        "content",
+        "msg",
+        "message",
+        "query",
+        "body",
+        "data",
+        "payload",
+    )
+    return (text or "").strip()
+
+
+def extract_external_id(payload: dict[str, Any]) -> str | None:
+    value = _pick(payload, "msg_id", "message_id", "msgid", "id", "uuid", "event_id")
+    return value[:128] if value else None
+
+
+def extract_sender(payload: dict[str, Any]) -> str | None:
+    value = _pick(payload, "from", "sender", "from_user", "user", "uid", "sender_id")
+    return value[:128] if value else None
+
+
+def split_command(text: str) -> tuple[str, str]:
+    """返回 (kind, 去掉前缀后的正文)。"""
+    head, _, rest = text.partition("\n")
+    probe = head.strip().lower()
+    for prefix in HELP_PREFIXES:
+        if probe == prefix or probe.startswith(f"{prefix}:") or probe.startswith(f"{prefix}："):
+            return "help", rest
+    for prefix in KNOWLEDGE_PREFIXES:
+        for sep in (":", "：", " ", "\u3000"):
+            if probe.startswith(f"{prefix}{sep}"):
+                offset = len(prefix) + len(sep)
+                return "knowledge", (head.strip()[offset:] + ("\n" + rest if rest else "")).strip()
+    for prefix in TASK_PREFIXES:
+        for sep in (":", "：", " ", "\u3000"):
+            if probe.startswith(f"{prefix}{sep}"):
+                offset = len(prefix) + len(sep)
+                return "task", (head.strip()[offset:] + ("\n" + rest if rest else "")).strip()
+    return "task", text
+
+
+def split_tags(body: str) -> tuple[str, list[str]]:
+    """把 `#标签` 摘出来。只认行首和空白后的 #，免得把 "C#" 吃掉。"""
+    tags: list[str] = []
+    kept: list[str] = []
+    for line in body.splitlines():
+        words = line.split(" ")
+        rest: list[str] = []
+        for word in words:
+            if word.startswith("#") and len(word) > 1 and not word[1:].isdigit():
+                name = word[1:].strip("，,。.;；")
+                if name and name.lower() not in {t.lower() for t in tags}:
+                    tags.append(name)
+                continue
+            rest.append(word)
+        kept.append(" ".join(rest).rstrip())
+    return "\n".join(kept).strip(), tags
+
+
+def split_title(body: str) -> tuple[str, str]:
+    lines = body.splitlines()
+    if not lines:
+        return "", ""
+    title = lines[0].strip()
+    rest = "\n".join(lines[1:]).strip()
+    return title[:MAX_TITLE], rest[:MAX_BODY]
+
+
+async def _creator_id(session: SessionDep, channel: BotChannel) -> uuid.UUID:
+    """消息记在谁名下：通道创建者；人没了就退回工作区 owner。"""
+    if channel.created_by is not None:
+        row = await session.execute(
+            select(Member.id).where(
+                Member.workspace_id == channel.workspace_id,
+                Member.user_id == channel.created_by,
+                Member.status == "active",
+            )
+        )
+        if row.first() is not None:
+            return channel.created_by
+    workspace = await session.get(Workspace, channel.workspace_id)
+    if workspace is None:  # 理论上不可能：FK 是 CASCADE
+        raise AppError(ErrorCode.BOT_TOKEN_INVALID, "接入通道不存在")
+    return workspace.owner_id
+
+
+async def _create_task(
+    session: SessionDep,
+    *,
+    ws_id: uuid.UUID,
+    creator_id: uuid.UUID,
+    title: str,
+    body: str,
+    tags: list[str],
+) -> Item:
+    item = Item(
+        workspace_id=ws_id,
+        kind="task",
+        title=title,
+        body_md=body,
+        status="inbox",
+        priority=0,
+        creator_id=creator_id,
+    )
+    session.add(item)
+    await session.flush()
+    if tags:
+        await _set_tags(session, ws_id, item, tags)
+    await _log(session, item, creator_id, "created", {"via": "wechat_clawbot"})
+    return item
+
+
+async def _create_knowledge(
+    session: SessionDep,
+    *,
+    ws_id: uuid.UUID,
+    creator_id: uuid.UUID,
+    title: str,
+    body: str,
+    tags: list[str],
+) -> Item:
+    item = Item(
+        workspace_id=ws_id,
+        kind="knowledge",
+        title=title,
+        body_md=body,
+        status="draft",
+        creator_id=creator_id,
+    )
+    session.add(item)
+    await session.flush()
+    doc = KnowledgeDoc(
+        item_id=item.id,
+        workspace_id=ws_id,
+        author_id=creator_id,
+        source_item_id=None,
+        source_kind="manual",
+        doc_type="note",
+        status_hint="draft",
+        generated_by="human",
+    )
+    session.add(doc)
+    await session.flush()
+    if tags:
+        await _set_tags(session, ws_id, item, tags)
+    await _log(session, item, creator_id, "knowledge_created", {"via": "wechat_clawbot"})
+    return item
+
+
+def _link(request: Request, ws_id: uuid.UUID, item: Item) -> str:
+    base = str(request.base_url).rstrip("/")
+    # base_url 形如 http://host:8200/api/v1/，而页面在站点根上
+    base = base.split("/api/")[0]
+    if item.kind == "knowledge":
+        return f"{base}/w/{ws_id}/knowledge/{item.id}"
+    return f"{base}/w/{ws_id}?open={item.id}"
+
+
+async def _channel_by_token(session: SessionDep, token: str) -> BotChannel:
+    from sqlalchemy import text as sql_text
+
+    # 策略要靠这个值才放行那一行，必须先设。
+    await session.execute(
+        sql_text("SELECT set_config('app.bot_token_hash', :h, true)"), {"h": hash_token(token)}
+    )
+    row = (
+        await session.execute(select(BotChannel).where(BotChannel.token_hash == hash_token(token)))
+    ).scalar_one_or_none()
+    if row is None:
+        raise AppError(ErrorCode.BOT_TOKEN_INVALID, "接入通道不存在或令牌已失效")
+    return row
+
+
+@webhook_router.get("/clawbot/{token}")
+async def clawbot_verify(
+    token: str, session: SessionDep, echostr: str | None = Query(default=None)
+):
+    """clawbot 后台通常先 GET 一次确认地址是活的：有 echostr 就原样回。"""
+    channel = await _channel_by_token(session, token)
+    if channel.status != "active":
+        raise AppError(ErrorCode.BOT_DISABLED, "这个通道已停用")
+    if echostr is not None:
+        return PlainTextResponse(echostr)
+    return ok({"channel": channel.name, "status": channel.status})
+
+
+@webhook_router.post("/clawbot/{token}")
+async def clawbot_message(
+    token: str,
+    request: Request,
+    session: SessionDep,
+    payload: Annotated[dict[str, Any] | None, Body()] = None,
+):
+    channel = await _channel_by_token(session, token)
+    if channel.status != "active":
+        raise AppError(ErrorCode.BOT_DISABLED, "这个通道已停用")
+
+    raw: dict[str, Any] = payload if isinstance(payload, dict) else {}
+    text = extract_text(raw)
+    external_id = extract_external_id(raw)
+    sender = extract_sender(raw)
+
+    await bind_tenant(session, channel.workspace_id, channel.created_by)
+
+    # 重推：同一个外部消息 id 再来一次，回上次那句，不再建第二条。
+    if external_id:
+        previous = (
+            await session.execute(
+                select(BotMessage).where(
+                    BotMessage.channel_id == channel.id,
+                    BotMessage.external_id == external_id,
+                )
+            )
+        ).scalar_one_or_none()
+        if previous is not None:
+            channel.last_seen_at = datetime.now(timezone.utc)
+            return ok({"reply": previous.reply, "action": previous.action, "duplicate": True})
+
+    message = BotMessage(
+        workspace_id=channel.workspace_id,
+        channel_id=channel.id,
+        external_id=external_id,
+        sender=sender,
+        text=text[:MAX_BODY],
+        action="ignored",
+        reply="",
+        raw=raw if isinstance(raw, dict) else {"value": raw},
+    )
+
+    if not text:
+        message.action = "ignored"
+        message.reply = "没收到正文，只收到一个空壳。"
+        session.add(message)
+        return ok({"reply": message.reply, "action": "ignored"})
+
+    kind, body = split_command(text)
+    creator_id = await _creator_id(session, channel)
+
+    if kind == "help":
+        message.action = "help"
+        message.reply = HELP_TEXT
+    else:
+        body, tags = split_tags(body)
+        title, rest = split_title(body)
+        if not title:
+            message.action = "ignored"
+            message.reply = "只有标签没有内容，这条没记。"
+        elif kind == "knowledge":
+            item = await _create_knowledge(
+                session,
+                ws_id=channel.workspace_id,
+                creator_id=creator_id,
+                title=title,
+                body=rest,
+                tags=tags,
+            )
+            message.action = "knowledge"
+            message.item_id = item.id
+            link = _link(request, channel.workspace_id, item)
+            message.reply = f"已记成知识草稿：《{item.title}》。去核对：{link}"
+        else:
+            item = await _create_task(
+                session,
+                ws_id=channel.workspace_id,
+                creator_id=creator_id,
+                title=title,
+                body=rest,
+                tags=tags,
+            )
+            message.action = "task"
+            message.item_id = item.id
+            message.reply = (
+                f"已记成任务：《{item.title}》。打开：{_link(request, channel.workspace_id, item)}"
+            )
+
+    channel.last_seen_at = datetime.now(timezone.utc)
+    channel.last_error = None
+    try:
+        # 用 SAVEPOINT 兜住唯一索引冲突：另一个并发请求刚插了同一条消息，
+        # 这里只要认输回同一句就行，不能把整笔事务打挂。
+        async with session.begin_nested():
+            session.add(message)
+            await session.flush()
+    except IntegrityError:
+        if external_id:
+            previous = (
+                await session.execute(
+                    select(BotMessage).where(
+                        BotMessage.channel_id == channel.id,
+                        BotMessage.external_id == external_id,
+                    )
+                )
+            ).scalar_one_or_none()
+            if previous is not None:
+                return ok({"reply": previous.reply, "action": previous.action, "duplicate": True})
+        raise AppError(ErrorCode.BOT_TOKEN_INVALID, "同一条消息重复到达，已忽略") from None
+
+    return ok({"reply": message.reply, "action": message.action, "duplicate": False})
+
+
+# ── 工作区里的管理接口（登录 + admin 以上） ─────────────────────────────
+
+
+def _channel_out(channel: BotChannel) -> dict[str, Any]:
+    return {
+        "id": str(channel.id),
+        "kind": channel.kind,
+        "name": channel.name,
+        "status": channel.status,
+        "created_by": str(channel.created_by) if channel.created_by else None,
+        "last_seen_at": channel.last_seen_at,
+        "last_error": channel.last_error,
+        "created_at": channel.created_at,
+    }
+
+
+def _webhook_url(request: Request, token: str) -> str:
+    base = str(request.base_url).rstrip("/")
+    return f"{base}/integrations/clawbot/{token}"
+
+
+@admin_router.get("/{ws_id}/integrations")
+async def list_integrations(ws_id: uuid.UUID, ctx: AdminDep, session: SessionDep):
+    rows = (
+        (
+            await session.execute(
+                select(BotChannel)
+                .where(BotChannel.workspace_id == ws_id)
+                .order_by(BotChannel.created_at.desc())
+            )
+        )
+        .scalars()
+        .all()
+    )
+    return ok({"items": [_channel_out(row) for row in rows]})
+
+
+@admin_router.post("/{ws_id}/integrations")
+async def create_integration(
+    ws_id: uuid.UUID,
+    ctx: AdminDep,
+    session: SessionDep,
+    request: Request,
+    body: Annotated[dict[str, Any] | None, Body()] = None,
+):
+    name = str((body or {}).get("name") or "").strip()[:64] or "微信"
+    token = new_token()
+    channel = BotChannel(
+        workspace_id=ws_id,
+        kind="wechat_clawbot",
+        name=name,
+        token_hash=hash_token(token),
+        status="active",
+        created_by=ctx.user.id,
+    )
+    session.add(channel)
+    await session.flush()
+    return ok(
+        {
+            "channel": _channel_out(channel),
+            # 令牌只在这里出现一次，之后只能"重新生成"。
+            "token": token,
+            "webhook_url": _webhook_url(request, token),
+        }
+    )
+
+
+@admin_router.patch("/{ws_id}/integrations/{channel_id}")
+async def update_integration(
+    ws_id: uuid.UUID,
+    channel_id: uuid.UUID,
+    ctx: AdminDep,
+    session: SessionDep,
+    body: Annotated[dict[str, Any] | None, Body()] = None,
+):
+    channel = await session.get(BotChannel, channel_id)
+    if channel is None or channel.workspace_id != ws_id:
+        raise AppError(ErrorCode.BOT_TOKEN_INVALID, "接入通道不存在")
+    data = body or {}
+    if isinstance(data.get("name"), str):
+        channel.name = data["name"].strip()[:64]
+    if isinstance(data.get("status"), str):
+        if data["status"] not in ("active", "disabled"):
+            raise AppError(ErrorCode.VALIDATION_ERROR, "状态只能是 active 或 disabled")
+        channel.status = data["status"]
+    return ok({"channel": _channel_out(channel)})
+
+
+@admin_router.post("/{ws_id}/integrations/{channel_id}/rotate")
+async def rotate_integration(
+    ws_id: uuid.UUID,
+    channel_id: uuid.UUID,
+    ctx: AdminDep,
+    session: SessionDep,
+    request: Request,
+):
+    channel = await session.get(BotChannel, channel_id)
+    if channel is None or channel.workspace_id != ws_id:
+        raise AppError(ErrorCode.BOT_TOKEN_INVALID, "接入通道不存在")
+    token = new_token()
+    channel.token_hash = hash_token(token)
+    return ok(
+        {
+            "channel": _channel_out(channel),
+            "token": token,
+            "webhook_url": _webhook_url(request, token),
+        }
+    )
+
+
+@admin_router.delete("/{ws_id}/integrations/{channel_id}")
+async def delete_integration(
+    ws_id: uuid.UUID, channel_id: uuid.UUID, ctx: AdminDep, session: SessionDep
+):
+    channel = await session.get(BotChannel, channel_id)
+    if channel is None or channel.workspace_id != ws_id:
+        raise AppError(ErrorCode.BOT_TOKEN_INVALID, "接入通道不存在")
+    await session.delete(channel)
+    return ok({"deleted": True})
+
+
+@admin_router.get("/{ws_id}/integrations/{channel_id}/messages")
+async def list_messages(
+    ws_id: uuid.UUID,
+    channel_id: uuid.UUID,
+    ctx: AdminDep,
+    session: SessionDep,
+    limit: int = Query(default=20, ge=1, le=100),
+):
+    rows = (
+        (
+            await session.execute(
+                select(BotMessage)
+                .where(BotMessage.workspace_id == ws_id, BotMessage.channel_id == channel_id)
+                .order_by(BotMessage.created_at.desc())
+                .limit(limit)
+            )
+        )
+        .scalars()
+        .all()
+    )
+    return ok(
+        {
+            "items": [
+                {
+                    "id": str(row.id),
+                    "text": row.text,
+                    "action": row.action,
+                    "item_id": str(row.item_id) if row.item_id else None,
+                    "reply": row.reply,
+                    "sender": row.sender,
+                    "created_at": row.created_at,
+                }
+                for row in rows
+            ]
+        }
+    )
+
+
+__all__ = ["webhook_router", "admin_router"]
@@ -79,6 +79,10 @@ class ErrorCode(IntEnum):
    # 9xxx 客户端发布（OTA）
    APP_RELEASE_NOT_FOUND = 9001

+    # 9xxx 外部接入（微信 clawbot 等）
+    BOT_TOKEN_INVALID = 9002
+    BOT_DISABLED = 9003
+

 # 默认 HTTP 状态：业务码自己带语义，HTTP 只是传输层
 _HTTP_STATUS: dict[ErrorCode, int] = {
@@ -135,6 +139,8 @@ _HTTP_STATUS: dict[ErrorCode, int] = {
    ErrorCode.ATTACHMENT_FORBIDDEN: 403,
    ErrorCode.CONFIRM_REQUIRED: 409,
    ErrorCode.APP_RELEASE_NOT_FOUND: 404,
+    ErrorCode.BOT_TOKEN_INVALID: 404,
+    ErrorCode.BOT_DISABLED: 403,
 }


@@ -16,7 +16,16 @@ from starlette.responses import Response
 from starlette.staticfiles import StaticFiles
 from starlette.types import Scope

-from .api import app_release, attachments, auth, items, knowledge, tickets, workspaces
+from .api import (
+    app_release,
+    attachments,
+    auth,
+    integrations,
+    items,
+    knowledge,
+    tickets,
+    workspaces,
+)
 from .api import settings as settings_api
 from .config import get_settings
 from .db import SessionFactory, current_app_role, engine
@@ -118,6 +127,8 @@ app.include_router(knowledge.router, prefix=settings.api_prefix)
 app.include_router(attachments.router, prefix=settings.api_prefix)
 app.include_router(app_release.router, prefix=settings.api_prefix)
 app.include_router(settings_api.router, prefix=settings.api_prefix)
+app.include_router(integrations.admin_router, prefix=settings.api_prefix)
+app.include_router(integrations.webhook_router, prefix=settings.api_prefix)


@app.get("/health", tags=["运维"], summary="存活探针")
@@ -0,0 +1,89 @@
+"""外部接入：微信（clawbot）这一类的机器人通道。
+
+为什么单开一张表而不是塞进 `system_setting`：
+
+1. 一个工作区可以挂多个通道（自己的号、公司的号），也随时可能换；
+   塞进 setting 的 JSON 里就没法"停用这一个、保留那一个"。
+2. 通道是**租户数据**：谁能往里发消息，取决于它属于哪个工作区。
+   租户表就得有 `workspace_id NOT NULL` + RLS（AGENTS.md 第 2.5 条）。
+
+令牌只存 sha256：数据库被看见也拿不到能用的令牌；令牌只在创建时回显一次。
+"""
+
+from __future__ import annotations
+
+import uuid
+from datetime import datetime
+
+from sqlalchemy import DateTime, ForeignKey, Index, String, Text, text
+from sqlalchemy.dialects.postgresql import JSONB
+from sqlalchemy.dialects.postgresql import UUID as PgUUID
+from sqlalchemy.orm import Mapped, mapped_column
+
+from .models import Base, Timestamps, new_uuid
+
+BOT_KINDS = ("wechat_clawbot",)
+BOT_STATUSES = ("active", "disabled")
+
+INTEGRATION_TENANT_TABLES = ("bot_channel", "bot_message")
+
+
+class BotChannel(Base, Timestamps):
+    """一条接入通道：微信里那个机器人 ⇄ 本工作区。"""
+
+    __tablename__ = "bot_channel"
+    __table_args__ = (
+        Index("ix_bot_channel_ws", "workspace_id"),
+        Index("uq_bot_channel_token", "token_hash", unique=True),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(PgUUID(as_uuid=True), primary_key=True, default=new_uuid)
+    workspace_id: Mapped[uuid.UUID] = mapped_column(
+        PgUUID(as_uuid=True), ForeignKey("workspace.id", ondelete="CASCADE"), nullable=False
+    )
+    kind: Mapped[str] = mapped_column(String(32), nullable=False, default="wechat_clawbot")
+    name: Mapped[str] = mapped_column(String(64), nullable=False, default="")
+    # hex(sha256(令牌))。令牌本身只在创建响应里出现一次。
+    token_hash: Mapped[str] = mapped_column(String(64), nullable=False)
+    status: Mapped[str] = mapped_column(String(16), nullable=False, default="active")
+    # 消息落在谁名下：用创建这条通道的人；人没了就退回工作区 owner。
+    created_by: Mapped[uuid.UUID | None] = mapped_column(
+        PgUUID(as_uuid=True), ForeignKey("app_user.id", ondelete="SET NULL")
+    )
+    last_seen_at: Mapped[datetime | None] = mapped_column(DateTime(timezone=True))
+    last_error: Mapped[str | None] = mapped_column(Text)
+
+
+class BotMessage(Base, Timestamps):
+    """收到的每条消息都留痕：出问题时能回答"那条任务到底有没有进去"。"""
+
+    __tablename__ = "bot_message"
+    __table_args__ = (
+        Index("ix_bot_message_channel", "channel_id", "created_at"),
+        # 同一个外部消息 id 只处理一次：微信会重推，重推不能变成两条任务。
+        Index(
+            "uq_bot_message_external",
+            "channel_id",
+            "external_id",
+            unique=True,
+            postgresql_where=text("external_id IS NOT NULL"),
+        ),
+    )
+
+    id: Mapped[uuid.UUID] = mapped_column(PgUUID(as_uuid=True), primary_key=True, default=new_uuid)
+    workspace_id: Mapped[uuid.UUID] = mapped_column(
+        PgUUID(as_uuid=True), ForeignKey("workspace.id", ondelete="CASCADE"), nullable=False
+    )
+    channel_id: Mapped[uuid.UUID] = mapped_column(
+        PgUUID(as_uuid=True), ForeignKey("bot_channel.id", ondelete="CASCADE"), nullable=False
+    )
+    external_id: Mapped[str | None] = mapped_column(String(128))
+    sender: Mapped[str | None] = mapped_column(String(128))
+    text: Mapped[str] = mapped_column(Text, nullable=False, default="")
+    # task / knowledge / help / ignored / error
+    action: Mapped[str] = mapped_column(String(24), nullable=False, default="ignored")
+    item_id: Mapped[uuid.UUID | None] = mapped_column(
+        PgUUID(as_uuid=True), ForeignKey("item.id", ondelete="SET NULL")
+    )
+    reply: Mapped[str] = mapped_column(Text, nullable=False, default="")
+    raw: Mapped[dict] = mapped_column(JSONB, nullable=False, default=dict)