Merge remote-tracking branch 'origin/master' into ji

offline-backend-20260512/backend/packages/harness/deerflow/config/__init__.py

@@ -1,5 +1,6 @@
 from .app_config import get_app_config
 from .extensions_config import ExtensionsConfig, get_extensions_config
+from .gateway_config import GatewayConfig
 from .memory_config import MemoryConfig, get_memory_config
 from .paths import Paths, get_paths
 from .skill_evolution_config import SkillEvolutionConfig
@@ -20,6 +21,7 @@ __all__ = [
     "SkillsConfig",
     "ExtensionsConfig",
     "get_extensions_config",
+    "GatewayConfig",
     "MemoryConfig",
     "get_memory_config",
     "get_tracing_config",

offline-backend-20260512/backend/packages/harness/deerflow/config/app_config.py

@@ -13,6 +13,7 @@ from deerflow.config.agents_api_config import AgentsApiConfig, load_agents_api_c
 from deerflow.config.checkpointer_config import CheckpointerConfig, load_checkpointer_config_from_dict
 from deerflow.config.database_config import DatabaseConfig
 from deerflow.config.extensions_config import ExtensionsConfig
+from deerflow.config.gateway_config import GatewayConfig
 from deerflow.config.guardrails_config import GuardrailsConfig, load_guardrails_config_from_dict
 from deerflow.config.memory_config import MemoryConfig, load_memory_config_from_dict
 from deerflow.config.model_config import ModelConfig
@@ -122,6 +123,7 @@ class AppConfig(BaseModel):
     skill_stop: SkillStopConfig = Field(default_factory=SkillStopConfig, description="Skill stop middleware configuration")
     model_config = ConfigDict(extra="allow")
     database: DatabaseConfig = Field(default_factory=DatabaseConfig, description="Unified database backend configuration")
+    gateway: GatewayConfig = Field(default_factory=GatewayConfig, description="Gateway FastAPI listening port (used by intra-process loopback)")
     run_events: RunEventsConfig = Field(default_factory=RunEventsConfig, description="Run event storage configuration")
     checkpointer: CheckpointerConfig | None = Field(default=None, description="Checkpointer configuration")
     stream_bridge: StreamBridgeConfig | None = Field(default=None, description="Stream bridge configuration")

offline-backend-20260512/backend/packages/harness/deerflow/config/gateway_config.py

@@ -0,0 +1,46 @@
+"""Gateway 进程的本机绑定配置。
+
+目前唯一字段是 ``port``——Gateway FastAPI 的监听端口。圆桌三路由
+(intent / recommend / multi_agent) 内部用 loopback 调本机的其它 endpoint
+(``/api/threads``、``/api/agents`` 等),需要知道这个端口才能拼出 base URL。
+
+为什么放在配置里而不是写死
+--------------------------
+- 部署方常常会改 Gateway 监听端口(端口被占用、合规要求、容器化端口映射),
+  写死代码意味着每次改端口都得改源码 + 重新构建/分发,**改 config 不需要重启二进制**
+- ``DEER_FLOW_GATEWAY_PORT`` 环境变量仍然是更高优先级的紧急覆盖通道,适合
+  临时调试或者 docker-compose / k8s 注入
+
+修改方式(部署侧)
+------------------
+在 ``config.yaml`` 顶层加:
+
+.. code-block:: yaml
+
+    gateway:
+      port: 9999        # 默认 8001;部署机改了 gateway 端口时改这里
+
+只想临时改一次(不动 yaml)→ 设环境变量:
+
+.. code-block:: bash
+
+    export DEER_FLOW_GATEWAY_PORT=9999
+"""
+
+from __future__ import annotations
+
+from pydantic import BaseModel, Field
+
+
+class GatewayConfig(BaseModel):
+    """Gateway 本机 loopback 端口配置。"""
+
+    port: int = Field(
+        default=8001,
+        ge=1,
+        le=65535,
+        description=(
+            "Gateway FastAPI 监听端口。圆桌内部 loopback 调用会拼到 "
+            "``http://127.0.0.1:<port>``。默认 8001(与 Makefile/scripts/start-all.sh 对齐)。"
+        ),
+    )