feat(chat): 推荐问法 API + Agent 软超时默认 45s (#114)

* feat(chat): 推荐问法 API + Agent 软超时默认 45s

- GET /api/py/chat/suggested-questions 供 Ink BFF 转发
- AGENT_MAX_LATENCY_MS 未设时默认 45000，降低 Intent 慢于 15s 即 V1 降级的误触发

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(tech-graph): manifest 登记 GET /api/py/chat/suggested-questions

对齐 api/index.py chat_suggested_questions，修复 manifest_check CI。

Co-authored-by: Cursor <cursoragent@cursor.com>

* fix(tech-graph): drift_check 与 graph.json 同步 suggested-questions

- 00_main.md / 00_main.ai.md 登记 GET /api/py/chat/suggested-questions
- export graph.json 节点 SQ

Co-authored-by: Cursor <cursoragent@cursor.com>

---------

Co-authored-by: cyning <cyning12@gmail.com>
Co-authored-by: Cursor <cursoragent@cursor.com>

Author: 3 people

api/agent.py

@@ -85,7 +85,7 @@ def __init__(
         self._tools = {t.name: t for t in tools}
         self._memory = memory
         self._max_steps = max(1, int(os.getenv("AGENT_MAX_STEPS", "5")))
-        self._max_latency_ms = max(1000, int(os.getenv("AGENT_MAX_LATENCY_MS", "15000")))
+        self._max_latency_ms = max(1000, int(os.getenv("AGENT_MAX_LATENCY_MS", "45000")))
         self._min_confidence = float(os.getenv("INTENT_MIN_CONFIDENCE", "0.6"))
 
     def _select_tool(self, tool_name: ToolName) -> Tool:

api/index.py

@@ -1142,3 +1142,20 @@ async def py_admin_ingest(
             status = 400
         return JSONResponse({"ok": False, "error": msg}, status_code=status)
 
+
+@app.get("/api/py/chat/suggested-questions")
+def chat_suggested_questions() -> JSONResponse:
+    """返回推荐问法列表，供前端展示（不再本地写死）。"""
+    return JSONResponse(
+        {
+            "ok": True,
+            "questions": [
+                "《AI 编程可闭环协作》卷三讲什么？Harness 和签收是什么？",
+                "Tech Graph 是什么",
+                "冷/温/热 和 架构三层 区别？",
+                "简单介绍下刘新宁",
+                "AI Ink Brain 的架构是怎样的",
+            ],
+        }
+    )
+

docs/_tech_graph/00_main.ai.md

@@ -43,6 +43,9 @@ flowchart TD
   E --"GET /api/py/chat/history"--> H1[[Chat History]]
   // → api/index.py chat_history
 
+  E --"GET /api/py/chat/suggested-questions"--> SQ[[Suggested Questions]]
+  // → api/index.py chat_suggested_questions
+
   E --"GET /api/py/chatbi/access/verify"--> CV[[ChatBI Access Verify]]
   // → api/index.py chatbi_access_verify
 
@@ -101,12 +104,17 @@ flowchart TD
 - `POST /api/py/chain/chat` → `chain_chat_route`  // → `api/index.py::chain_chat_route`
 - `POST /api/py/chat` → `chat`  // → `api/index.py::chat`
 - `GET /api/py/chat/history` → `chat_history`  // → `api/index.py::chat_history`
+- `GET /api/py/chat/suggested-questions` → `chat_suggested_questions`  // → `api/index.py::chat_suggested_questions`
 - `GET /api/py/chatbi/access/verify` → `chatbi_access_verify`  // → `api/index.py::chatbi_access_verify`
 - `POST /api/py/code/query` → `code_query`  // → `api/index.py::code_query`
 - `POST /api/py/code/search` → `code_search`  // → `api/index.py::code_search`
 - `GET /api/py/health` → `health`  // → `api/index.py::health`
+- `GET /api/py/live` → `live`  // → `api/index.py::live`
+- `GET /api/py/ready` → `ready`  // → `api/index.py::ready`
 - `POST /api/py/text2sql/chat` → `text2sql_chat`  // → `api/index.py::text2sql_chat`
 - `POST /api/py/unified/chat` → `unified_chat_route`  // → `api/index.py::unified_chat_route`
+- `POST /api/py/unified/chat/graph` → `unified_chat_graph_route`  // → `api/index.py::unified_chat_graph_route`
+- `POST /api/py/unified/chat/graph/stream` → `unified_chat_graph_stream_route`  // → `api/index.py::unified_chat_graph_stream_route`
 - `POST /api/py/unified/chat/stream` → `unified_chat_stream_route`  // → `api/index.py::unified_chat_stream_route`
 
 #### Anchors（from manifest）

docs/_tech_graph/00_main.md

@@ -10,6 +10,7 @@ flowchart TD
     E -->|Unified Stream| U2[SSE 流式<br/>/api/py/unified/chat/stream<br/>api/index.py#L576 unified_chat_stream_route<br/>api/unified_chat.py::handle_unified_chat_stream]
     E -->|遗留 Chat| C1[RAG Chat<br/>/api/py/chat<br/>api/index.py#L591 chat]
     E -->|History| H1[Chat History<br/>/api/py/chat/history<br/>api/index.py chat_history]
+    E -->|Suggested| SQ[Suggested Questions<br/>/api/py/chat/suggested-questions<br/>api/index.py chat_suggested_questions]
     E -->|ChatBI verify| CV[Access Verify<br/>GET /api/py/chatbi/access/verify<br/>api/index.py chatbi_access_verify]
     E -->|Health| HL[Health<br/>/api/py/health<br/>api/index.py health]
     E -->|Chain Chat| CH[Chain Timeline<br/>/api/py/chain/chat<br/>api/index.py#L546 chain_chat_route<br/>api/chain_chat.py::handle_chain_chat]

docs/_tech_graph/_manifest.json

@@ -52,6 +52,15 @@
         "symbol": "chat_history"
       }
     },
+    {
+      "method": "GET",
+      "path": "/api/py/chat/suggested-questions",
+      "handler": "chat_suggested_questions",
+      "anchor": {
+        "path": "api/index.py",
+        "symbol": "chat_suggested_questions"
+      }
+    },
     {
       "method": "POST",
       "path": "/api/py/chain/chat",

docs/_tech_graph/graph.json

@@ -160,6 +160,16 @@
       "to": "OBS_DOC",
       "type": "depends_on"
     },
+    {
+      "anchors": [],
+      "from": "E",
+      "graph_id": "00_main",
+      "label": "GET /api/py/chat/suggested-questions",
+      "mark": "->",
+      "sync": true,
+      "to": "SQ",
+      "type": "depends_on"
+    },
     {
       "anchors": [],
       "from": "E",
@@ -2199,7 +2209,7 @@
     }
   ],
   "freeze_id": "TECH_GRAPH_S2_FREEZE_20260519_V2_3",
-  "generated_at": "2026-05-18T07:07:16Z",
+  "generated_at": "2026-06-04T08:24:47Z",
   "graphs": [
     {
       "id": "00_main",
@@ -2788,6 +2798,11 @@
       "id": "SPEC",
       "label": ">docs/text2sql/v1/sql/supabase_init.sql"
     },
+    {
+      "graph_id": "00_main",
+      "id": "SQ",
+      "label": "Suggested Questions"
+    },
     {
       "graph_id": "14_runtime_observability",
       "id": "SQLR",

tests/test_chat_suggested_questions_route.py

@@ -0,0 +1,25 @@
+from __future__ import annotations
+
+import importlib
+
+import pytest
+from fastapi.testclient import TestClient
+
+
+def test_chat_suggested_questions_returns_list(monkeypatch: pytest.MonkeyPatch) -> None:
+    monkeypatch.setenv("SYNC_ADMIN_SECRET", "secret-token-1234567890")
+    monkeypatch.setenv("CHATBI_USE_AGENT", "false")
+
+    index = importlib.import_module("api.index")
+    importlib.reload(index)
+
+    client = TestClient(index.app)
+    res = client.get("/api/py/chat/suggested-questions")
+
+    assert res.status_code == 200
+    data = res.json()
+    assert data["ok"] is True
+    questions = data["questions"]
+    assert isinstance(questions, list)
+    assert len(questions) >= 1
+    assert all(isinstance(q, str) and q.strip() for q in questions)