页面空泡 + 发不出新问题
        │
        ▼
① 查 messages：status / error / query / created_at
        │
        ├─ status 仍在处理中，error 为空  → 真的还在跑，看 api / agent_backend 卡在哪
        │
        └─ status = error，error 有内容   → 已经失败，页面只是没显示
                │
                ▼
② 同一句 query 出现几次？  → 本次同一句失败 3 次，对应 UI 的 3/3
                │
                ▼
③ 读 error 原文
                │
                ├─ token limit exceeded  → 去核对 Agent 的 max_tokens
                ├─ timeout / 连接失败     → 去看模型服务、插件、网络
                └─ 其它业务报错           → 按报错本文继续
                │
                ▼
④ 查 agent_config_snapshots + agent_config_drafts 的 max_tokens
                │
                ▼
⑤ 对照会话长度：前面多轮问答 + 知识库检索片段，是否可能把 Prompt 顶满
                │
                ▼
⑥ 结论：不是卡住，是 2048 太小；临时刷新新开对话，正式改回 8192

#!/usr/bin/env bash
set -euo pipefail

docker exec docker-db_postgres-1 psql -U postgres -d dify -c "
SELECT id,
       conversation_id,
       status,
       answer IS NOT NULL AS has_answer,
       left(query, 80) AS q,
       left(error, 180) AS err,
       created_at,
       updated_at
FROM messages
ORDER BY created_at DESC
LIMIT 8;
"

Model token limit (2048) exceeded before any response was generated.
Increase the `max_tokens` model setting, or simplify the prompt

#!/usr/bin/env bash
set -euo pipefail

docker logs --since 20m docker-api-1 2>&1 | grep -i 'token limit'
docker logs --since 20m docker-agent_backend-1 2>&1 | grep -i 'token limit'
docker logs --since 20m docker-worker-1 2>&1 | grep -iE 'error|timeout|Traceback|token limit' | tail -30

SELECT s.id,
       s.version,
       s.config_snapshot::json -> 'model' -> 'model_settings' -> 'max_tokens' AS max_tokens
FROM agent_config_snapshots s
JOIN agents a ON s.agent_id = a.id
WHERE a.app_id = '40e95fd3-e7f5-44f2-a03b-dc3e60413540'
ORDER BY s.version DESC;

id                                   | version | max_tokens
-------------------------------------+---------+-----------
01a0135c-320e-79dc-97a0-94da9b904c13 |       2 | 2048
01a012e7-bed6-7151-ac28-91fcdaab31c3 |       1 |

SELECT id,
       config_snapshot::json -> 'model' -> 'model_settings' -> 'max_tokens' AS max_tokens
FROM agent_config_drafts
WHERE agent_id = '01a012e7-bed3-7574-b0d1-a5cc79a0d3de'
ORDER BY updated_at DESC NULLS LAST;

id                                   | max_tokens
-------------------------------------+-----------
01a012e7-bf60-7673-a894-64551d984a23 | 2048

系统提示 + 历史 + 检索片段 + 本轮问句  >= 2048

#!/usr/bin/env bash
set -euo pipefail

docker exec -it docker-db_postgres-1 psql -U postgres -d dify

-- 最新活动快照
SELECT s.id, s.version,
       s.config_snapshot::json -> 'model' -> 'model_settings' -> 'max_tokens' AS max_tokens
FROM agent_config_snapshots s
JOIN agents a ON s.agent_id = a.id
WHERE a.app_id = '40e95fd3-e7f5-44f2-a03b-dc3e60413540'
ORDER BY s.version DESC;

-- 草稿
SELECT d.id,
       d.config_snapshot::json -> 'model' -> 'model_settings' -> 'max_tokens' AS max_tokens
FROM agent_config_drafts d
WHERE d.agent_id = '01a012e7-bed3-7574-b0d1-a5cc79a0d3de'
ORDER BY d.updated_at DESC NULLS LAST;

#!/usr/bin/env bash
set -euo pipefail

docker exec docker-db_postgres-1 psql -U postgres -d dify -t -A -c \
  "SELECT config_snapshot FROM agent_config_snapshots WHERE id='01a0135c-320e-79dc-97a0-94da9b904c13'" \
  > backup_snap_before_8192.json

docker exec docker-db_postgres-1 psql -U postgres -d dify -t -A -c \
  "SELECT config_snapshot FROM agent_config_drafts WHERE id='01a012e7-bf60-7673-a894-64551d984a23'" \
  > backup_draft_before_8192.json

BEGIN;

UPDATE agent_config_snapshots
SET config_snapshot = jsonb_set(
      config_snapshot::jsonb,
      '{model,model_settings,max_tokens}',
      '8192'::jsonb
    )::text
WHERE id = '01a0135c-320e-79dc-97a0-94da9b904c13';

UPDATE agent_config_drafts
SET config_snapshot = jsonb_set(
      config_snapshot::jsonb,
      '{model,model_settings,max_tokens}',
      '8192'::jsonb
    )::text
WHERE id = '01a012e7-bf60-7673-a894-64551d984a23';

COMMIT;

BEGIN
UPDATE 1
UPDATE 1
COMMIT

ROLLBACK;

-- 错：字符串 8192，后续可能当文本而不是数字
'"8192"'::jsonb

SELECT 'snapshot' AS which,
       id,
       config_snapshot::json -> 'model' -> 'model_settings' -> 'max_tokens' AS max_tokens
FROM agent_config_snapshots
WHERE id = '01a0135c-320e-79dc-97a0-94da9b904c13'

UNION ALL

SELECT 'draft',
       id,
       config_snapshot::json -> 'model' -> 'model_settings' -> 'max_tokens'
FROM agent_config_drafts
WHERE id = '01a012e7-bf60-7673-a894-64551d984a23';

which    | id                                   | max_tokens
---------+--------------------------------------+-----------
snapshot | 01a0135c-320e-79dc-97a0-94da9b904c13 | 8192
draft    | 01a012e7-bf60-7673-a894-64551d984a23 | 8192

SELECT config_snapshot::json -> 'model' -> 'model_settings'
FROM agent_config_snapshots
WHERE id = '01a0135c-320e-79dc-97a0-94da9b904c13';

{
  "stop": null,
  "top_p": null,
  "max_tokens": 8192,
  "temperature": null,
  "response_format": null,
  "presence_penalty": null,
  "frequency_penalty": null
}

BEGIN;

UPDATE agent_config_snapshots
SET config_snapshot = '这里粘贴 backup_snap_before_8192.json 的完整内容'
WHERE id = '01a0135c-320e-79dc-97a0-94da9b904c13';

UPDATE agent_config_drafts
SET config_snapshot = '这里粘贴 backup_draft_before_8192.json 的完整内容'
WHERE id = '01a012e7-bf60-7673-a894-64551d984a23';

COMMIT;

BEGIN;

UPDATE agent_config_snapshots
SET config_snapshot = jsonb_set(
      config_snapshot::jsonb,
      '{model,model_settings,max_tokens}',
      '2048'::jsonb
    )::text
WHERE id = '01a0135c-320e-79dc-97a0-94da9b904c13';

UPDATE agent_config_drafts
SET config_snapshot = jsonb_set(
      config_snapshot::jsonb,
      '{model,model_settings,max_tokens}',
      '2048'::jsonb
    )::text
WHERE id = '01a012e7-bf60-7673-a894-64551d984a23';

COMMIT;

BEGIN;

UPDATE agent_config_snapshots
SET config_snapshot = jsonb_set(
      config_snapshot::jsonb,
      '{model,model_settings,max_tokens}',
      '8192'::jsonb
    )::text
WHERE id = '01a0135c-320e-79dc-97a0-94da9b904c13';

UPDATE agent_config_drafts
SET config_snapshot = jsonb_set(
      config_snapshot::jsonb,
      '{model,model_settings,max_tokens}',
      '8192'::jsonb
    )::text
WHERE id = '01a012e7-bf60-7673-a894-64551d984a23';

COMMIT;

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""专题十二 · 步骤 1：查最近 messages，判断空泡是卡住还是已失败。"""
from __future__ import annotations

import sys

import _bootstrap  # noqa: F401
import _config as C
from dify_api import Dify


def main() -> int:
    d = Dify(C.DIFY_EMAIL, C.DIFY_PASSWORD)
    try:
        d.login()
        sql = (
            "docker exec %s psql -U postgres -d dify -c "
            "\"SELECT id, conversation_id, status, answer IS NOT NULL AS has_answer, "
            "left(query, 80) AS q, left(error, 180) AS err, created_at "
            "FROM messages ORDER BY created_at DESC LIMIT 8;\"" % C.PG_CONTAINER
        )
        out, err = d.sh(sql)
        print(out or err)
        if "token limit" in (out or "").lower():
            print("\n[提示] 发现 token limit 报错 —— 继续运行专题十二后续脚本")
        return 0
    finally:
        d.close()


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""专题十二 · 步骤 2：核对 Agent 活动快照与草稿 max_tokens（应对上 error 里的数字）。"""
from __future__ import annotations

import sys

import _bootstrap  # noqa: F401
import _config as C
from dify_api import Dify


def main() -> int:
    d = Dify(C.DIFY_EMAIL, C.DIFY_PASSWORD)
    try:
        d.login()
        snap_sql = (
            "docker exec %s psql -U postgres -d dify -c "
            "\"SELECT s.id, s.version, "
            "s.config_snapshot::json -> 'model' -> 'model_settings' -> 'max_tokens' AS max_tokens "
            "FROM agent_config_snapshots s JOIN agents a ON s.agent_id = a.id "
            "WHERE a.app_id = '%s' ORDER BY s.version DESC;\"" % (C.PG_CONTAINER, C.APP_ID)
        )
        out1, _ = d.sh(snap_sql)
        print("=== 活动快照 ===")
        print(out1.strip())
        draft_sql = (
            "docker exec %s psql -U postgres -d dify -c "
            "\"SELECT id, config_snapshot::json -> 'model' -> 'model_settings' -> 'max_tokens' "
            "AS max_tokens FROM agent_config_drafts WHERE agent_id = '%s' "
            "ORDER BY updated_at DESC NULLS LAST;\"" % (C.PG_CONTAINER, C.AGENT_ID)
        )
        out2, _ = d.sh(draft_sql)
        print("\n=== 编辑草稿 ===")
        print(out2.strip())
        return 0
    finally:
        d.close()


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""专题十二 · 步骤 3：改回 8192 前备份快照与草稿 JSON。"""
from __future__ import annotations

import sys

import _bootstrap  # noqa: F401
import _agent_db as A
import _config as C
from dify_api import Dify


def main() -> int:
    d = Dify(C.DIFY_EMAIL, C.DIFY_PASSWORD)
    try:
        d.login()
        A.backup_snapshot(d, "agent_config_snapshots", C.SNAP_ID, "snap_before_8192")
        A.backup_snapshot(d, "agent_config_drafts", C.DRAFT_ID, "draft_before_8192")
        return 0
    finally:
        d.close()


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""专题十二 · 步骤 4 · 修改后：把 max_tokens 从 2048 改回 8192（快照+草稿，勿点发布）。"""
from __future__ import annotations

import sys

import _bootstrap  # noqa: F401
import _agent_db as A
import _config as C
from dify_api import Dify


def main() -> int:
    d = Dify(C.DIFY_EMAIL, C.DIFY_PASSWORD)
    try:
        d.login()
        sql = "BEGIN;\n"
        for table, rid in (
            ("agent_config_snapshots", C.SNAP_ID),
            ("agent_config_drafts", C.DRAFT_ID),
        ):
            sql += (
                "UPDATE %s SET config_snapshot = jsonb_set("
                "config_snapshot::jsonb, '{model,model_settings,max_tokens}', '%s'::jsonb)::text "
                "WHERE id='%s';\n" % (table, C.MAX_TOKENS_DEFAULT, rid)
            )
        sql += "COMMIT;\n"
        print(A.psql(d, sql))
        A.verify_max_tokens(d, C.SNAP_ID, C.DRAFT_ID)
        print("\n[WARN] 改完不要点「构建/发布」；请新开对话验证")
        return 0
    finally:
        d.close()


if __name__ == "__main__":
    sys.exit(main())

#!/usr/bin/env python3
# -*- coding: utf-8 -*-
"""专题十二 · 步骤 5：验证 max_tokens 已改回 8192，并扫 api 日志无 token limit。"""
from __future__ import annotations

import sys

import _bootstrap  # noqa: F401
import _agent_db as A
import _config as C
from dify_api import Dify


def main() -> int:
    d = Dify(C.DIFY_EMAIL, C.DIFY_PASSWORD)
    try:
        d.login()
        A.verify_max_tokens(d, C.SNAP_ID, C.DRAFT_ID)
        snap = A.read_max_tokens(d, "agent_config_snapshots", C.SNAP_ID)
        draft = A.read_max_tokens(d, "agent_config_drafts", C.DRAFT_ID)
        ok = str(snap) == str(C.MAX_TOKENS_DEFAULT) and str(draft) == str(C.MAX_TOKENS_DEFAULT)
        out, _ = d.sh(
            "docker logs --since 30m docker-api-1 2>&1 | grep -i 'token limit' | tail -5"
        )
        print("\n=== 最近 api token limit 日志 ===")
        print(out.strip() or "(无新 token limit 日志)")
        print("\n[OK]" if ok else "\n[FAIL]", "期望 snapshot/draft 均为", C.MAX_TOKENS_DEFAULT)
        return 0 if ok else 1
    finally:
        d.close()


if __name__ == "__main__":
    sys.exit(main())