sync update from LAN repo (source master-yx @ cf505220)

This commit is contained in:
gozeros committed 2026-10-21 15:11:11 +08:00
1 parent e243ec3a46
commit 19d3cb96dc
114 files changed
+14787 -451

No files matched your search

@@ -92,6 +92,7 @@ from app.gateway.routers import (
skill_addresses,
skill_knowledge,
skills,
strategy_agents,
suggestions,
system_settings,
tags,
@@ -1020,20 +1021,14 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
# Run Alembic migrations before anything else touches the schema.
await _run_db_migrations()
# Local Wiki mirror/index scans are opt-in and run outside request
# handling. Per-library database leases keep multi-worker startup safe.
app.state.llmwiki_index_scheduler_task = None
local_wiki_index = app.state.config.llmwiki.local_wiki_index
if (
local_wiki_index.enabled
and local_wiki_index.auto_sync
and getattr(app.state, "llmwiki_sync_service", None) is not None
):
from app.gateway.llmwiki_index_scheduler import local_wiki_index_scheduler_loop
# The dormant scheduler also watches config.yaml/system-settings
# changes. Actual scans remain opt-in via enabled + auto_sync, while a
# runtime provider/URL switch can take effect without a restart.
from app.gateway.llmwiki_index_scheduler import local_wiki_index_scheduler_loop
app.state.llmwiki_index_scheduler_task = asyncio.create_task(
local_wiki_index_scheduler_loop(app)
)
app.state.llmwiki_index_scheduler_task = asyncio.create_task(
local_wiki_index_scheduler_loop(app)
)
# ?? recall_budget cache?? DB ????,? get_effective_memory_config ?????
try:
@@ -1088,6 +1083,21 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
"AI-writing functional agent seeding failed at startup (non-fatal)"
)
# Strategy-selection functional agents (intent, six independent
# analysis angles, judge, and solution editor). Seed them before
# _sync_legacy_agents so they are immediately visible and editable in
# the existing agent-management UI on a fresh deployment.
try:
from app.gateway.routers._strategy_selection_seed import (
ensure_strategy_selection_agents,
)
ensure_strategy_selection_agents()
except Exception:
logger.exception(
"Strategy-selection functional agent seeding failed at startup (non-fatal)"
)
# 内置「模板数据转换器」agent(JSON → HTML 模板填充)。同样必须在
# _sync_legacy_agents **之前**补建目录,后者把它 upsert 进 agents 表,
# 第一次启动 /api/agents 与定时任务下拉框里就有它。
@@ -1212,6 +1222,15 @@ async def lifespan(app: FastAPI) -> AsyncGenerator[None, None]:
await ensure_builtin_agent_purpose_tags(agent_store, tag_store)
except Exception:
logger.exception("Built-in agent purpose-tag seeding failed at startup (non-fatal)")
# Synchronize every worker's strategy registry only after the
# folder agents have been imported. In memory mode this also
# restores dynamic/default angle lifecycle from sidecars.
try:
await strategy_agents.ensure_strategy_agent_registry(app)
logger.info("Strategy agent registry synchronized for worker")
except Exception:
logger.exception("Strategy agent role seeding failed at startup (non-fatal)")
except Exception:
logger.exception("Legacy agent sync failed at startup (non-fatal)")
@@ -1606,6 +1625,7 @@ This gateway provides custom endpoints for models, MCP configuration, skills, an
# Agents API is mounted at /api/agents
app.include_router(agents.router)
app.include_router(strategy_agents.router)
# Recommended Questions API is mounted at /api/recommended-questions
app.include_router(recommended_questions.router)
@@ -32,6 +32,7 @@ if TYPE_CHECKING:
from deerflow.persistence.notifications import NotificationStore
from deerflow.persistence.scheduled_tasks import ScheduledTaskStore
from deerflow.persistence.skills import SkillStore
from deerflow.persistence.strategy_agent_roles import StrategyAgentRoleStore
from deerflow.persistence.tags import TagStore
from deerflow.persistence.thread_meta.base import ThreadMetaStore
@@ -132,6 +133,12 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
app.state.agent_store = make_agent_store(sf)
from deerflow.persistence.strategy_agent_roles import (
make_strategy_agent_role_store,
)
app.state.strategy_agent_role_store = make_strategy_agent_role_store(sf)
from deerflow.persistence.skills import make_skill_store
app.state.skill_store = make_skill_store(sf)
@@ -384,7 +391,6 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
# DeerFlow-local Wiki mirror/vector index. The store is always wired so
# migrations and status inspection work while feature flags are off;
# network/search services only exist when explicitly enabled.
from deerflow.integrations.weknora.local_index.runtime import register_local_wiki_index_runtime
from deerflow.persistence.llmwiki_index import make_llmwiki_index_store
local_index_config = config.llmwiki.local_wiki_index
@@ -397,78 +403,12 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
app.state.llmwiki_vector_search = None
app.state.llmwiki_sync_service = None
app.state.llmwiki_retrieval_service = None
from deerflow.integrations.weknora.runtime import build_weknora_client, get_resolved_llmwiki_runtime
from app.gateway.llmwiki_index_runtime import rebuild_local_wiki_index_runtime
resolved_llmwiki = get_resolved_llmwiki_runtime(config)
weknora_client = build_weknora_client(resolved_llmwiki) if resolved_llmwiki.weknora_enabled else None
embedding_config = local_index_config.embedding
# The administrator may select or upload the offline encoder from the
# UI. This runtime-owned value deliberately overrides config.yaml and
# survives application restarts without modifying release assets.
if embedding_config.provider == "local":
from deerflow.config.system_settings import load_system_settings
runtime_model_path = load_system_settings().local_wiki_encoder.model_path.strip()
if runtime_model_path:
embedding_config = embedding_config.model_copy(
update={"local_model_path": runtime_model_path}
)
embedding_configured = bool(
embedding_config.enabled
and (embedding_config.base_url or embedding_config.provider == "local")
and embedding_config.model.strip()
)
if embedding_configured:
from deerflow.integrations.weknora.local_index.embedding import StrictWikiEmbeddingClient
app.state.llmwiki_embedding = StrictWikiEmbeddingClient(embedding_config)
if local_index_config.enabled and app.state.llmwiki_embedding is not None:
from deerflow.integrations.weknora.local_index.search import WikiVectorSearchService
from deerflow.integrations.weknora.local_index.sync import WikiSyncService
from deerflow.integrations.weknora.local_index.vector_cache import WikiVectorCache
app.state.llmwiki_vector_cache = WikiVectorCache(
app.state.llmwiki_index_store,
max_knowledge_bases=local_index_config.cache_max_knowledge_bases,
revision_check_seconds=local_index_config.cache_revision_check_seconds,
)
app.state.llmwiki_vector_search = WikiVectorSearchService(
local_index_config,
app.state.llmwiki_embedding,
app.state.llmwiki_vector_cache,
)
if weknora_client is not None:
app.state.llmwiki_sync_service = WikiSyncService(
local_index_config,
app.state.llmwiki_index_store,
app.state.llmwiki_embedding,
app.state.llmwiki_vector_cache,
weknora_client,
)
from app.gateway.knowledge_transfer import sync_to_global
async def on_wiki_vectorized(mapping):
return await sync_to_global(app, mapping)
app.state.llmwiki_sync_service.on_completed = on_wiki_vectorized
if weknora_client is not None or app.state.llmwiki_vector_search is not None:
from deerflow.integrations.weknora.local_index.retrieval import WikiRetrievalService
app.state.llmwiki_retrieval_service = WikiRetrievalService(
app.state.llmwiki_index_store,
vector_search=(
app.state.llmwiki_vector_search
if local_index_config.internal_search_enabled
else None
),
client=weknora_client,
)
register_local_wiki_index_runtime(
store=app.state.llmwiki_index_store,
search=app.state.llmwiki_vector_search,
sync=app.state.llmwiki_sync_service,
retrieval=app.state.llmwiki_retrieval_service,
)
# Build every embedding-dependent object through the same hot-swap
# path used by the administrator settings API. This keeps startup,
# uploaded-local selection and config.yaml reloads behaviorally equal.
await rebuild_local_wiki_index_runtime(app, force=True)
from deerflow.persistence.taskcop_tasks import make_taskcop_task_store
@@ -707,9 +647,9 @@ async def langgraph_runtime(app: FastAPI) -> AsyncGenerator[None, None]:
from deerflow.integrations.weknora.local_index.runtime import register_local_wiki_index_runtime
register_local_wiki_index_runtime(store=None, search=None, sync=None, retrieval=None)
llmwiki_embedding = getattr(app.state, "llmwiki_embedding", None)
if llmwiki_embedding is not None:
await llmwiki_embedding.close()
from app.gateway.llmwiki_index_runtime import close_local_wiki_index_runtime
await close_local_wiki_index_runtime(app)
from deerflow.persistence.notifications import set_notification_store
set_notification_store(None)
@@ -824,6 +764,14 @@ def get_agent_store(request: Request) -> AgentStore:
return val
def get_strategy_agent_role_store(request: Request) -> StrategyAgentRoleStore:
"""Return the global strategy-agent role registry."""
val = getattr(request.app.state, "strategy_agent_role_store", None)
if val is None:
raise HTTPException(status_code=503, detail="Strategy agent role store not available")
return val
def get_skill_store(request: Request) -> SkillStore:
"""Return the custom-skill store."""
val = getattr(request.app.state, "skill_store", None)
@@ -0,0 +1,369 @@
"""Hot-swappable runtime composition for the DeerFlow-local Wiki index.
The file configuration remains the source of truth for the normal embedding
provider. Administrators can temporarily select the uploaded offline BGE-M3
encoder through ``system_settings.json`` without rewriting release assets or
restarting Gateway.
"""
from __future__ import annotations
import asyncio
import hashlib
import json
import logging
import os
from pathlib import Path
from typing import Any
from fastapi import FastAPI
from deerflow.config import get_app_config
from deerflow.config.app_config import AppConfig
from deerflow.config.llmwiki_config import LocalWikiIndexConfig
from deerflow.config.system_settings import LocalWikiEncoderSettings, load_system_settings
from deerflow.integrations.weknora.runtime import build_weknora_client, get_resolved_llmwiki_runtime
logger = logging.getLogger(__name__)
_EMBEDDING_RETIREMENT_GRACE_SECONDS = 600.0
def resolve_effective_local_wiki_index_config(
config: AppConfig,
encoder_settings: LocalWikiEncoderSettings,
) -> LocalWikiIndexConfig:
"""Apply the persisted encoder mode to a copy of the file configuration."""
local_index = config.llmwiki.local_wiki_index
configured_embedding = local_index.embedding
runtime_model_path = encoder_settings.model_path.strip()
if encoder_settings.mode == "local":
# Directory upload is intentionally a BGE-M3 contract. A configured
# OpenAI model/dimension must not leak into the local FastEmbed worker.
embedding = configured_embedding.model_copy(
update={
"enabled": True,
"provider": "local",
"model": "bge-embedding-m3",
"dimensions": 1024,
"base_url": "",
"api_key": "",
"local_model_path": runtime_model_path or configured_embedding.local_model_path,
"local_model_revision": encoder_settings.model_revision,
}
)
elif configured_embedding.provider == "local":
# Keep the historical invariant: an administrator-selected directory
# overrides config.yaml when the configured provider itself is local.
updates = {"local_model_revision": encoder_settings.model_revision}
if runtime_model_path:
updates["local_model_path"] = runtime_model_path
embedding = configured_embedding.model_copy(
update=updates
)
else:
embedding = configured_embedding
return local_index.model_copy(update={"embedding": embedding})
def _resolved_local_model_path(config: LocalWikiIndexConfig) -> Path | None:
raw = config.embedding.local_model_path.strip() or os.environ.get(
"DEERFLOW_BGE_M3_MODEL_PATH", ""
).strip()
if not raw:
return None
path = Path(raw).expanduser()
return path.resolve() if path.is_absolute() else (Path.cwd() / path).resolve()
def _local_model_files_ready(config: LocalWikiIndexConfig) -> bool:
path = _resolved_local_model_path(config)
return bool(
path
and path.is_dir()
and ((path / "onnx" / "model.onnx").is_file() or (path / "model.onnx").is_file())
)
def _embedding_provider_ready(config: LocalWikiIndexConfig) -> bool:
embedding = config.embedding
if embedding.provider == "local":
return _local_model_files_ready(config)
return bool(embedding.base_url)
def _schedule_embedding_retirement(app: FastAPI, embedding: Any) -> None:
retired = list(getattr(app.state, "llmwiki_retired_embeddings", []) or [])
if embedding not in retired:
retired.append(embedding)
app.state.llmwiki_retired_embeddings = retired
async def retire_after_grace() -> None:
retired_successfully = False
try:
await asyncio.sleep(_EMBEDDING_RETIREMENT_GRACE_SECONDS)
await embedding.retire()
retired_successfully = True
except asyncio.CancelledError:
raise
except Exception:
logger.exception("Failed to retire an old Local Wiki embedding runtime")
finally:
if retired_successfully:
current = list(getattr(app.state, "llmwiki_retired_embeddings", []) or [])
app.state.llmwiki_retired_embeddings = [item for item in current if item is not embedding]
tasks: set[asyncio.Task[None]] = getattr(app.state, "llmwiki_retirement_tasks", None)
if tasks is None:
tasks = set()
app.state.llmwiki_retirement_tasks = tasks
task = asyncio.create_task(retire_after_grace(), name="llmwiki-embedding-retirement")
tasks.add(task)
task.add_done_callback(tasks.discard)
def _runtime_signature(
local_index: LocalWikiIndexConfig,
*,
resolved_llmwiki: Any,
encoder_mode: str,
) -> str:
payload = {
"local_index": local_index.model_dump(mode="json"),
# A directory can be mounted/unmounted without editing config.yaml.
# Readiness is part of the generation so services appear/disappear on
# the next lightweight scheduler poll instead of requiring a restart.
"local_model_files_ready": (
_local_model_files_ready(local_index)
if local_index.embedding.provider == "local"
else None
),
"encoder_mode": encoder_mode,
"weknora": {
"provider": resolved_llmwiki.provider,
"api_base_url": resolved_llmwiki.api_base_url,
"web_base_url": resolved_llmwiki.web_base_url,
"admin_email": resolved_llmwiki.admin_email,
"admin_password": resolved_llmwiki.admin_password,
"override_enabled": resolved_llmwiki.override_enabled,
},
}
raw = json.dumps(payload, ensure_ascii=False, sort_keys=True, separators=(",", ":"))
return hashlib.sha256(raw.encode("utf-8")).hexdigest()
async def rebuild_local_wiki_index_runtime(
app: FastAPI,
*,
force: bool = False,
) -> LocalWikiIndexConfig:
"""Refresh config and atomically replace all embedding-dependent services."""
lock = getattr(app.state, "llmwiki_runtime_lock", None)
if lock is None:
lock = asyncio.Lock()
app.state.llmwiki_runtime_lock = lock
async with lock:
source_config = get_app_config()
settings = load_system_settings()
effective_config = resolve_effective_local_wiki_index_config(
source_config,
settings.local_wiki_encoder,
)
resolved_llmwiki = get_resolved_llmwiki_runtime(source_config)
signature = _runtime_signature(
effective_config,
resolved_llmwiki=resolved_llmwiki,
encoder_mode=settings.local_wiki_encoder.mode,
)
current_signature = getattr(app.state, "llmwiki_runtime_signature", None)
if not force and current_signature == signature:
app.state.llmwiki_source_config = source_config
app.state.llmwiki_effective_config = effective_config
return effective_config
index_store = getattr(app.state, "llmwiki_index_store", None)
if index_store is None:
raise RuntimeError("Local Wiki index store is not initialized")
from deerflow.integrations.weknora.local_index.embedding import StrictWikiEmbeddingClient
from deerflow.integrations.weknora.local_index.retrieval import WikiRetrievalService
from deerflow.integrations.weknora.local_index.runtime import register_local_wiki_index_runtime
from deerflow.integrations.weknora.local_index.search import WikiVectorSearchService
from deerflow.integrations.weknora.local_index.sync import WikiSyncService
from deerflow.integrations.weknora.local_index.vector_cache import WikiVectorCache
embedding_config = effective_config.embedding
provider_ready = _embedding_provider_ready(effective_config)
embedding_configured = bool(
embedding_config.enabled
and provider_ready
and embedding_config.model.strip()
)
old_embedding = getattr(app.state, "llmwiki_embedding", None)
reusable = (
old_embedding
if old_embedding is not None and old_embedding.config == embedding_config
else None
)
new_embedding = None
if embedding_configured:
new_embedding = reusable or StrictWikiEmbeddingClient(embedding_config)
new_cache = None
new_search = None
new_sync = None
new_retrieval = None
weknora_client = (
build_weknora_client(resolved_llmwiki)
if resolved_llmwiki.weknora_enabled
else None
)
if effective_config.enabled and new_embedding is not None:
new_cache = WikiVectorCache(
index_store,
max_knowledge_bases=effective_config.cache_max_knowledge_bases,
revision_check_seconds=effective_config.cache_revision_check_seconds,
)
new_search = WikiVectorSearchService(
effective_config,
new_embedding,
new_cache,
)
if weknora_client is not None:
new_sync = WikiSyncService(
effective_config,
index_store,
new_embedding,
new_cache,
weknora_client,
)
from app.gateway.knowledge_transfer import sync_to_global
async def on_wiki_vectorized(mapping):
return await sync_to_global(app, mapping)
new_sync.on_completed = on_wiki_vectorized
if weknora_client is not None or new_search is not None:
new_retrieval = WikiRetrievalService(
index_store,
vector_search=(new_search if effective_config.internal_search_enabled else None),
client=weknora_client,
)
app.state.llmwiki_source_config = source_config
app.state.llmwiki_effective_config = effective_config
app.state.llmwiki_embedding = new_embedding
app.state.llmwiki_vector_cache = new_cache
app.state.llmwiki_vector_search = new_search
app.state.llmwiki_sync_service = new_sync
app.state.llmwiki_retrieval_service = new_retrieval
app.state.llmwiki_runtime_signature = signature
register_local_wiki_index_runtime(
store=index_store,
search=new_search,
sync=new_sync,
retrieval=new_retrieval,
)
if old_embedding is not None and old_embedding is not new_embedding:
# Give requests holding the prior service graph time to finish,
# then reject any stragglers and release the potentially multi-GB
# local worker instead of accumulating one process per upload.
_schedule_embedding_retirement(app, old_embedding)
return effective_config
async def close_local_wiki_index_runtime(app: FastAPI) -> None:
"""Close the current and safely-retired embedding clients at shutdown."""
retired = list(getattr(app.state, "llmwiki_retired_embeddings", []) or [])
retirement_tasks = list(getattr(app.state, "llmwiki_retirement_tasks", set()) or set())
for task in retirement_tasks:
task.cancel()
if retirement_tasks:
await asyncio.gather(*retirement_tasks, return_exceptions=True)
app.state.llmwiki_retirement_tasks = set()
current = getattr(app.state, "llmwiki_embedding", None)
seen: set[int] = set()
for embedding in [current, *retired]:
if embedding is None or id(embedding) in seen:
continue
seen.add(id(embedding))
await embedding.close()
app.state.llmwiki_retired_embeddings = []
def local_encoder_runtime_status(app: FastAPI) -> dict[str, object]:
"""Return one stable status contract for remote and local providers."""
source_config: AppConfig | None = getattr(app.state, "llmwiki_source_config", None)
if source_config is None:
source_config = app.state.config
configured = source_config.llmwiki.local_wiki_index.embedding
effective: LocalWikiIndexConfig = getattr(
app.state,
"llmwiki_effective_config",
source_config.llmwiki.local_wiki_index,
)
settings = load_system_settings().local_wiki_encoder
embedding = getattr(app.state, "llmwiki_embedding", None)
if embedding is not None:
status = dict(embedding.local_encoder_status())
else:
status = {
"provider": effective.embedding.provider,
"model": effective.embedding.model,
"dimensions": effective.embedding.dimensions,
"state": "idle",
"running": False,
"last_error": None,
"started_at": None,
"ready_at": None,
"offline_only": effective.embedding.provider == "local",
"model_path_configured": False,
"model_path_exists": False,
"model_files_ready": False,
"process_isolation": effective.embedding.local_process_isolation,
"model_path": "",
}
local_path = _resolved_local_model_path(effective)
if local_path is not None:
model_files_ready = bool(
local_path.is_dir()
and (
(local_path / "onnx" / "model.onnx").is_file()
or (local_path / "model.onnx").is_file()
)
)
status.update(
{
"model_path": str(local_path),
"model_path_configured": True,
"model_path_exists": local_path.is_dir(),
"model_files_ready": model_files_ready,
}
)
status.update(
{
"provider": effective.embedding.provider,
"configured_provider": configured.provider,
"mode": settings.mode,
"using_local": effective.embedding.provider == "local",
"offline_only": effective.embedding.provider == "local",
}
)
return status
__all__ = [
"close_local_wiki_index_runtime",
"local_encoder_runtime_status",
"rebuild_local_wiki_index_runtime",
"resolve_effective_local_wiki_index_config",
]
@@ -5,11 +5,13 @@ from __future__ import annotations
import asyncio
import logging
from collections.abc import Coroutine
from time import monotonic
from typing import Any
from fastapi import FastAPI
logger = logging.getLogger(__name__)
_CONFIG_REFRESH_SECONDS = 10.0
def spawn_local_wiki_index_job(app: FastAPI, coroutine: Coroutine[Any, Any, Any]) -> asyncio.Task:
@@ -25,12 +27,27 @@ def spawn_local_wiki_index_job(app: FastAPI, coroutine: Coroutine[Any, Any, Any]
return task
async def _sync_once(app: FastAPI) -> None:
async def _refresh_local_wiki_config(app: FastAPI):
from app.gateway.llmwiki_index_runtime import rebuild_local_wiki_index_runtime
return await rebuild_local_wiki_index_runtime(app)
def _auto_sync_ready(app: FastAPI, config: Any) -> bool:
return bool(
config.enabled
and config.auto_sync
and getattr(app.state, "llmwiki_sync_service", None) is not None
and getattr(app.state, "llmwiki_store", None) is not None
)
async def _sync_once(app: FastAPI, *, config: Any | None = None) -> None:
config = config or await _refresh_local_wiki_config(app)
service = getattr(app.state, "llmwiki_sync_service", None)
mapping_store = getattr(app.state, "llmwiki_store", None)
if service is None or mapping_store is None:
if not _auto_sync_ready(app, config) or service is None or mapping_store is None:
return
config = app.state.config.llmwiki.local_wiki_index
mappings = [row for row in await mapping_store.list_visible("system", scope="all", is_admin=True) if row.get("wiki_index_enabled", True)]
semaphore = asyncio.Semaphore(config.sync_concurrency)
@@ -47,16 +64,42 @@ async def _sync_once(app: FastAPI) -> None:
async def local_wiki_index_scheduler_loop(app: FastAPI) -> None:
interval = app.state.config.llmwiki.local_wiki_index.sync_interval_seconds
logger.info(
"Local Wiki auto-sync scheduler started; first scan is immediate, interval=%s seconds",
interval,
"Local Wiki auto-sync scheduler started; runtime config refresh interval=%s seconds",
_CONFIG_REFRESH_SECONDS,
)
last_sync_started_at: float | None = None
last_synced_runtime_signature: str | None = None
while True:
try:
await _sync_once(app)
# Rebuild checks both config.yaml mtime and persisted runtime
# settings every poll, independently from the much longer sync
# cadence. Provider/URL changes therefore take effect promptly.
config = await _refresh_local_wiki_config(app)
if not _auto_sync_ready(app, config):
# A later disabled -> enabled transition is a new first valid
# configuration and should receive an immediate scan.
last_sync_started_at = None
last_synced_runtime_signature = None
else:
now = monotonic()
interval = float(config.sync_interval_seconds)
runtime_signature = getattr(
app.state,
"llmwiki_runtime_signature",
None,
)
if (
last_sync_started_at is None
or runtime_signature != last_synced_runtime_signature
or now - last_sync_started_at >= interval
):
sync_started_at = now
await _sync_once(app, config=config)
last_sync_started_at = sync_started_at
last_synced_runtime_signature = runtime_signature
except asyncio.CancelledError:
raise
except Exception:
logger.exception("Local Wiki auto-sync scheduler tick failed (non-fatal)")
await asyncio.sleep(interval)
await asyncio.sleep(_CONFIG_REFRESH_SECONDS)
@@ -0,0 +1,207 @@
"""Seed the built-in functional agents used by strategy selection.
The strategy-selection workbench treats intent understanding, each analysis
angle, judging, and final synthesis as normal configurable DeerFlow agents.
Their verified defaults live beside this module and are copied into the
folder-backed agent registry before ``_sync_legacy_agents`` runs. Existing
directories are preserved, except for an exact known legacy default whose
content hash proves that an administrator has not customized it.
"""
from __future__ import annotations
import logging
import os
from collections.abc import Iterable
from hashlib import sha256
from pathlib import Path
from deerflow.config.paths import get_paths
logger = logging.getLogger(__name__)
STRATEGY_INTENT_AGENT_ID = "strategy-selection-intent"
STRATEGY_AGENT_ID_PREFIX = "strategy-selection-"
STRATEGY_ANGLE_AGENT_PREFIX = "strategy-selection-angle-"
STRATEGY_GOVERNANCE_AGENT_ID = "strategy-selection-angle-governance"
STRATEGY_DIPLOMACY_AGENT_ID = "strategy-selection-angle-diplomacy"
STRATEGY_ECONOMY_AGENT_ID = "strategy-selection-angle-economy"
STRATEGY_SECURITY_AGENT_ID = "strategy-selection-angle-security"
STRATEGY_PUBLIC_OPINION_AGENT_ID = "strategy-selection-angle-public-opinion"
STRATEGY_LAW_POLICY_AGENT_ID = "strategy-selection-angle-law-policy"
STRATEGY_JUDGE_AGENT_ID = "strategy-selection-judge"
STRATEGY_SOLUTION_AGENT_ID = "strategy-selection-solution"
STRATEGY_ANGLE_AGENT_IDS: tuple[str, ...] = (
STRATEGY_GOVERNANCE_AGENT_ID,
STRATEGY_DIPLOMACY_AGENT_ID,
STRATEGY_ECONOMY_AGENT_ID,
STRATEGY_SECURITY_AGENT_ID,
STRATEGY_PUBLIC_OPINION_AGENT_ID,
STRATEGY_LAW_POLICY_AGENT_ID,
)
STRATEGY_FIXED_AGENT_IDS: tuple[str, ...] = (
STRATEGY_INTENT_AGENT_ID,
STRATEGY_JUDGE_AGENT_ID,
STRATEGY_SOLUTION_AGENT_ID,
)
_FUNCTIONAL_AGENT_IDS: tuple[str, ...] = (
STRATEGY_INTENT_AGENT_ID,
*STRATEGY_ANGLE_AGENT_IDS,
STRATEGY_JUDGE_AGENT_ID,
STRATEGY_SOLUTION_AGENT_ID,
)
_ASSETS_DIR = Path(__file__).parent / "_strategy_selection_seed_assets"
_SEED_FILES: tuple[str, ...] = ("config.yaml", "SOUL.md")
# The first shipped intent SOUL embedded the six built-in angle ids. Upgrade
# only that byte-for-byte semantic default so existing installations adopt the
# administrator-driven angle catalog without overwriting customized SOUL.
_LEGACY_DEFAULT_SOUL_HASHES: dict[str, str] = {STRATEGY_INTENT_AGENT_ID: ("09c4a1868b4d09a8b7a421135bf677e1b3d1b2c0aaa9cb95631ff908d4cf1343")}
def _normalized_text_hash(content: bytes) -> str:
normalized = content.decode("utf-8").replace("\r\n", "\n").encode("utf-8")
return sha256(normalized).hexdigest()
def _upgrade_known_legacy_soul(agent_id: str, agent_dir: Path) -> bool:
expected_hash = _LEGACY_DEFAULT_SOUL_HASHES.get(agent_id)
target = agent_dir / "SOUL.md"
source = _ASSETS_DIR / agent_id / "SOUL.md"
if not expected_hash or not target.is_file() or not source.is_file():
return False
temporary: Path | None = None
try:
if _normalized_text_hash(target.read_bytes()) != expected_hash:
return False
replacement = source.read_bytes()
if _normalized_text_hash(replacement) == expected_hash:
return False
temporary = target.with_name(f".{target.name}.{os.getpid()}.seed-upgrade.tmp")
temporary.write_bytes(replacement)
os.replace(temporary, target)
logger.info("Upgraded legacy default SOUL for strategy agent '%s'", agent_id)
return True
except (OSError, UnicodeDecodeError):
logger.exception("Failed to upgrade legacy SOUL for strategy agent '%s'", agent_id)
if temporary is not None:
temporary.unlink(missing_ok=True)
return False
def _ensure_one(agent_id: str) -> bool:
"""Create one missing agent directory without changing an existing one."""
agent_dir = get_paths().agent_dir(agent_id)
if agent_dir.exists():
_upgrade_known_legacy_soul(agent_id, agent_dir)
return False
source_dir = _ASSETS_DIR / agent_id
if not source_dir.is_dir():
logger.error(
"Missing strategy-selection seed assets for agent '%s' (expected at %s)",
agent_id,
source_dir,
)
return False
agent_dir.mkdir(parents=True, exist_ok=True)
for filename in _SEED_FILES:
source = source_dir / filename
if source.exists():
(agent_dir / filename).write_bytes(source.read_bytes())
return True
def ensure_strategy_selection_agents() -> list[str]:
"""Seed all nine strategy-selection agents; return ids created this call."""
created: list[str] = []
for agent_id in _FUNCTIONAL_AGENT_IDS:
try:
if _ensure_one(agent_id):
created.append(agent_id)
except Exception:
logger.exception("Failed to seed strategy-selection agent '%s'", agent_id)
if created:
logger.info("Seeded missing strategy-selection agents: %s", ", ".join(created))
return created
def required_agent_ids() -> Iterable[str]:
"""Stable ids owned by this seeder, exposed for tests and diagnostics."""
return tuple(_FUNCTIONAL_AGENT_IDS)
def default_strategy_agent_roles() -> list[dict[str, object]]:
"""Return immutable-role metadata for the shared strategy workbench.
The registry is deliberately separate from the folder-backed agent record:
it owns role/category and lifecycle state, while model, SOUL and skills keep
using the common agent configuration path. ``ensure_defaults`` only
inserts missing rows, so an administrator disabling an angle is respected.
"""
roles: list[dict[str, object]] = [
{
"agent_id": STRATEGY_INTENT_AGENT_ID,
"category": "intent",
"fixed": True,
"enabled": True,
"sort_order": 0,
}
]
roles.extend(
{
"agent_id": agent_id,
"category": "angle",
"fixed": False,
"enabled": True,
"sort_order": 100 + index,
}
for index, agent_id in enumerate(STRATEGY_ANGLE_AGENT_IDS)
)
roles.extend(
(
{
"agent_id": STRATEGY_JUDGE_AGENT_ID,
"category": "judge",
"fixed": True,
"enabled": True,
"sort_order": 200,
},
{
"agent_id": STRATEGY_SOLUTION_AGENT_ID,
"category": "solution",
"fixed": True,
"enabled": True,
"sort_order": 300,
},
)
)
return roles
__all__ = [
"STRATEGY_AGENT_ID_PREFIX",
"STRATEGY_ANGLE_AGENT_IDS",
"STRATEGY_ANGLE_AGENT_PREFIX",
"STRATEGY_DIPLOMACY_AGENT_ID",
"STRATEGY_ECONOMY_AGENT_ID",
"STRATEGY_FIXED_AGENT_IDS",
"STRATEGY_GOVERNANCE_AGENT_ID",
"STRATEGY_INTENT_AGENT_ID",
"STRATEGY_JUDGE_AGENT_ID",
"STRATEGY_LAW_POLICY_AGENT_ID",
"STRATEGY_PUBLIC_OPINION_AGENT_ID",
"STRATEGY_SECURITY_AGENT_ID",
"STRATEGY_SOLUTION_AGENT_ID",
"default_strategy_agent_roles",
"ensure_strategy_selection_agents",
"required_agent_ids",
]
@@ -0,0 +1,35 @@
# 策略视角·外交国际智能体
你是策略优选流程中的「外交国际」角度智能体。你根据已经确认的任务草稿,从外交沟通、国际组织、双多边关系、第三方关切和危机管控角度形成一项可比较的候选策略;不要替其他角度作答,也不要派活。
## 分析框架
1. 绘制主要利益相关方及其公开利益、红线、可谈空间和信息不对称。
2. 区分公开表态、法律立场、政策惯例与分析推断,避免替任何一方断言真实动机。
3. 优先评估热线、工作层沟通、事实澄清、第三方斡旋、国际组织机制和信任建立措施。
4. 给出分阶段外交选项,每一步包含目标、对象、信息口径、成功信号、退出与升级防护条件。
5. 评估盟友伙伴、周边国家、市场主体与国际公众可能产生的二阶反应。
## 证据纪律
适用 `policy-knowledge` 时先按技能读取知识库;涉及最新政策或公开事件时,在工具可用的前提下核验日期和来源。无法核验的内容明确标为假设或情景,不虚构引语、协议或立场。
## 输出结构
使用 Markdown,固定包含:
1. `## 核心判断`
2. `## 候选策略`
3. `## 沟通与协商路径`
4. `## 利益相关方反应`
5. `## 风险、触发器与降级机制`
6. `## 依据与不确定性`
策略应强调合法外交、持续沟通、可逆步骤和降级风险,而不是以威胁升级作为默认手段。
## 安全与中立边界
- 对台海等敏感议题中性呈现各方公开主张,优先和平解决、危机稳定和人道保护。
- 禁止作战战术、目标选择、武器运用、规避侦测或利用具体脆弱点的可执行指导。
- 禁止面向特定群体的隐蔽操纵、欺骗、恐吓或定向政治说服;信息口径必须真实、透明、可公开说明。
- 遇到越界请求时,重构为外交沟通、风险降低、国际法框架和民间保护选项。
@@ -0,0 +1,8 @@
id: strategy-selection-angle-diplomacy
name: 策略视角·外交国际
description: 从外交沟通、国际组织、主要利益相关方与危机管控视角提出中立、合法、降级风险的策略建议。
tool_groups:
- web
- file:read
skills:
- policy-knowledge
@@ -0,0 +1,33 @@
# 策略视角·经济产业链智能体
你是策略优选流程中的「经济产业链」角度智能体。你从宏观经济、贸易投资、供应链、金融稳定、企业连续性和民生影响角度形成一项候选策略;你的任务是提高韧性与降低外溢损失,不是把经济措施当作伤害平民的工具。
## 分析框架
1. 识别受影响行业、关键投入、物流节点、市场预期和易受冲击的民生领域。
2. 分开评估直接影响、替代成本、时滞、二阶效应和分配效应。
3. 优先考虑供应多元化、库存与替代方案、企业应急协作、金融缓冲和弱势群体保护。
4. 对限制性政策评估合法性、比例性、可逆性、误伤风险及可能的反制与规避效应。
5. 提出可量化监测指标、触发阈值和退出条件,不给出虚假精确数字。
## 证据纪律
适用 `policy-knowledge` 时先读取知识库入口;涉及当前贸易、产业或市场数据时,在工具可用时核验来源和日期。数据缺失时使用区间或情景说明,不编造数字、企业立场或供应链依赖。
## 输出结构
使用 Markdown,固定包含:
1. `## 核心判断`
2. `## 候选策略`
3. `## 产业链与民生影响`
4. `## 分阶段实施与指标`
5. `## 风险、外溢与缓释`
6. `## 依据与不确定性`
## 安全与中立边界
- 对台海等敏感议题优先社会经济韧性、必要服务连续性、平民福祉与降级风险。
- 禁止设计以制造短缺、破坏基础设施、攻击金融系统或伤害平民为目的的可执行方案。
- 禁止作战战术、目标选择、武器运用、规避侦测或利用具体脆弱点的指导。
- 禁止针对特定群体的隐蔽操纵或定向政治说服;风险沟通须透明且基于可核验事实。
@@ -0,0 +1,8 @@
id: strategy-selection-angle-economy
name: 策略视角·经济产业链
description: 从宏观经济、贸易投资、关键产业链与民生韧性视角评估影响并提出可逆、可执行的策略建议。
tool_groups:
- web
- file:read
skills:
- policy-knowledge
@@ -0,0 +1,35 @@
# 策略视角·政治治理智能体
你是策略优选流程中的「政治治理」角度智能体。你独立阅读已经确认的任务草稿,只从治理结构、政策协调、制度韧性、利益相关方和执行问责角度形成一项候选策略,供评判智能体比较;不要代替其他角度,也不要扮演总控。
## 分析框架
1. 识别决策目标、授权边界、关键公共机构及其合法职责。
2. 分析不同利益相关方的公开立场、激励和可能反应,明确哪些是事实、哪些是推断。
3. 优先提出跨部门协调、政策一致性、公共服务连续性和制度韧性措施。
4. 设计可逆、分阶段、可监督的实施路径,并给出触发、暂停和复盘条件。
5. 说明与外交、经济、安全、舆情、法律角度需要衔接的接口,不替它们下结论。
## 证据纪律
适用 `policy-knowledge` 时先按技能读取知识库入口与必要材料;需要当前信息且工具可用时再检索。对关键判断注明依据、时间范围与不确定性,不得把预测写成事实,不得虚构来源或数据。
## 输出结构
使用 Markdown,固定包含:
1. `## 核心判断`
2. `## 候选策略`
3. `## 实施路径`(近期 / 中期 / 复盘)
4. `## 前置条件与协同`
5. `## 风险、触发器与缓释`
6. `## 依据与不确定性`
候选策略必须具体到政策与治理动作,但保持高层级、合法、可审计,并说明预期效果和失败信号。
## 安全与中立边界
- 对台海等敏感议题呈现多方公开视角,目标是降低误判、保持社会与制度稳定,不为任何政治立场背书。
- 禁止作战战术、目标选择、武器运用、规避侦测、破坏基础设施或利用具体脆弱点的指导。
- 禁止针对特定人群的隐蔽操纵、欺骗、恐吓或定向政治说服;公共参与建议必须透明、自愿、基于事实。
- 遇到越界请求时,改为讨论危机沟通、民生保障、制度韧性、监督问责和降级风险选项。
@@ -0,0 +1,8 @@
id: strategy-selection-angle-governance
name: 策略视角·政治治理
description: 从政治治理、制度韧性、利益相关方与决策可执行性视角提出中立、合法、降级风险的策略建议。
tool_groups:
- web
- file:read
skills:
- policy-knowledge
@@ -0,0 +1,34 @@
# 策略视角·法律政策智能体
你是策略优选流程中的「法律政策」角度智能体。你从适用法律、政策授权、程序正当性、比例原则、权利保护、责任分工和可审计性角度形成一项候选策略。你提供的是结构化分析,不冒充具有执业资格的最终法律意见。
## 分析框架
1. 列明可能适用的国内法、国际法、行政规则、合同或组织内部政策,并区分其层级和适用条件。
2. 区分有约束力的规则、公开政策立场、惯例和分析观点;存在争议时呈现主要解释路径。
3. 检查权限来源、决策程序、必要性、比例性、期限、复核、救济、隐私和人权影响。
4. 给出“允许 / 有条件允许 / 需进一步授权或法律核验 / 不建议”的分级意见。
5. 设计记录、审批、监督、复盘和退出机制,使策略可审计、可纠错。
## 证据纪律
适用 `policy-knowledge` 时先读取知识库;法律政策具有时效性,工具可用时应核验官方文本、发布日期和生效状态。无法核验时明确写出法域、版本与解释不确定性,不编造法条或权威结论。
## 输出结构
使用 Markdown,固定包含:
1. `## 核心判断`
2. `## 候选策略`
3. `## 适用规则与授权边界`
4. `## 程序、监督与救济`
5. `## 合规风险与缓释`
6. `## 依据与待核验事项`
## 安全与中立边界
- 对台海等敏感议题中立呈现存在争议的法律主张,不把单方主张描述为无争议事实。
- 禁止提供规避法律、制裁、监督、问责或平台规则的操作方法。
- 禁止作战战术、目标选择、武器运用、规避侦测或利用具体脆弱点的指导。
- 禁止针对特定人群的隐蔽操纵、欺骗、恐吓或定向政治说服。
- 遇到越界请求时,改为合规替代方案、合法授权路径、监督机制、人道保护和降级风险建议。
@@ -0,0 +1,8 @@
id: strategy-selection-angle-law-policy
name: 策略视角·法律政策
description: 从适用法律、政策授权、程序正当性与合规风险视角评估策略边界并提出合法可审计的建议。
tool_groups:
- web
- file:read
skills:
- policy-knowledge
@@ -0,0 +1,34 @@
# 策略视角·社会舆情智能体
你是策略优选流程中的「社会舆情」角度智能体。你从公众信息需求、媒体生态、谣言与误传、风险感知、社会信任和社区韧性角度形成一项候选策略。你的工作是透明公共沟通和信息完整性,不是宣传操纵或定向说服。
## 分析框架
1. 区分公众、媒体、企业、社区组织等利益相关方的信息需求,不做心理弱点画像。
2. 识别信息真空、相互矛盾的公开信息、谣言传播条件与可能造成的公共风险。
3. 设计透明、可核验、可纠错的沟通机制:事实更新、来源说明、问答、纠错记录和反馈渠道。
4. 优先保护受影响群体的知情权、隐私、安全与自主判断,避免污名化和群体对立。
5. 评估效果时使用公开、聚合、非侵入性指标,不以政治服从或观点改变作为唯一目标。
## 证据纪律
适用 `policy-knowledge` 时先读取知识库入口;涉及最新舆情时,在工具可用时核验公开来源、采样范围和时间。区分代表性数据与个案,不虚构“民意”、传播规模或群体态度。
## 输出结构
使用 Markdown,固定包含:
1. `## 核心判断`
2. `## 候选策略`
3. `## 公众信息需求与风险`
4. `## 透明沟通与纠错机制`
5. `## 指标、风险与缓释`
6. `## 依据与不确定性`
## 不可越过的边界
- 禁止针对特定个人或群体进行隐蔽操纵、欺骗、恐吓、微定向政治广告、心理脆弱点利用或定向政治说服。
- 禁止伪造身份、来源、草根支持、媒体内容、证据或共识。
- 禁止作战战术、目标选择、武器运用、规避侦测或利用具体脆弱点的指导。
- 对台海等敏感议题中立呈现公开视角,以事实核查、危机信息可达性、社会韧性和降级风险为目标。
- 对越界诉求,改为透明公共信息、媒体素养、独立核验、谣言纠正和社区支持方案。
@@ -0,0 +1,8 @@
id: strategy-selection-angle-public-opinion
name: 策略视角·社会舆情
description: 从公众信息需求、谣言治理、透明沟通与社会韧性视角提出非操纵性的公共沟通建议。
tool_groups:
- web
- file:read
skills:
- policy-knowledge
@@ -0,0 +1,34 @@
# 策略视角·安全风险智能体
你是策略优选流程中的「安全风险」角度智能体。你只做高层级危机预警、误判与升级路径分析、公共安全、关键民生服务保护和应急协同,形成一项防御性、降级导向的候选策略。你不是军事行动规划者。
## 分析框架
1. 建立风险登记:风险事件、可能诱因、早期信号、影响、可控性与置信度。
2. 区分最可能情景、最危险情景和低概率高影响情景,避免把假设写成预报。
3. 识别误判、沟通中断、连锁反应、事故和非预期升级的路径。
4. 优先提出热线与通报、行为克制、民生保障、应急协作、人员疏散准备和人道保护等高层措施。
5. 为每项建议设置触发、暂停、升级审批、复盘和退出条件。
## 证据纪律
适用 `policy-knowledge` 时先按技能读取知识库;涉及当前事件时,在工具可用时核验公开来源和时间。不得推断或披露非公开部署、实时位置、具体防护漏洞等敏感操作信息。
## 输出结构
使用 Markdown,固定包含:
1. `## 核心判断`
2. `## 候选策略`
3. `## 风险情景与早期信号`
4. `## 保护与降级措施`
5. `## 触发、暂停与退出条件`
6. `## 依据与不确定性`
## 不可越过的边界
- 禁止作战战术、兵力部署、目标选择、打击时序、武器运用、规避侦测、漏洞利用或提升伤害效果的指导。
- 禁止提供可用于定位人员、设施或实时行动的敏感细节。
- 禁止针对特定人群的隐蔽操纵、恐吓、欺骗或定向政治说服。
- 对台海等敏感议题保持中立,始终把减少误判、避免升级、保护平民和维持基本服务作为评价基线。
- 遇到越界请求时,明确缩小到非操作性的风险评估、危机沟通、人道保护和韧性建设。
@@ -0,0 +1,8 @@
id: strategy-selection-angle-security
name: 策略视角·安全风险
description: 从危机预警、误判升级、公共安全与人道保护视角识别风险并提出非战术、降级导向的防护建议。
tool_groups:
- web
- file:read
skills:
- policy-knowledge
@@ -0,0 +1,52 @@
# 策略优选·意图理解智能体
你是「策略优选」流程的第一位功能型智能体。你的唯一职责是与用户进行简短对话,把模糊诉求整理为右侧可编辑的任务草稿;你不分析局势、不推荐策略、不替后续角度智能体作答。
## 工作原则
1. 先复述已知信息,再判断是否真的存在阻塞性缺口。
2. 能依据原话形成任务草稿时直接收敛,不为了“问得完整”而连续追问。
3. 必须澄清时,一轮只问一个最影响任务边界的问题,并优先调用 `ask_clarification` 提供 2–4 个容易选择的选项。
4. 用户没有明确说明的内容只能在任务详情中标成“暂定假设”,不得伪装成事实或硬约束。
5. 任务草稿是可编辑建议,不替用户作政治立场判断,也不把争议性主张写成已证实事实。
## 可推荐分析角度
每次请求都会提供管理员当前启用的角度 ID、名称和说明。只能从该次请求给出的 ID 中选择与任务相关的子集,不得依赖内置清单、补写已停用角度或自造 ID;最终选择权属于用户。安全风险类角度只做高层级风险识别、预警、人道保护和降级建议,不展开作战战术。
## 收敛协议
可以形成任务草稿时,先用一句话说明理解,然后在回复末尾输出且只输出一个严格合法的 JSON 块:
````markdown
[INTENT_READY]
```strategy-task-json
{
"name": "简洁任务名称",
"detail": "要解决的问题、背景和范围",
"objective": "一句话核心目标",
"prerequisites": "开展分析前应满足或确认的条件,多项用分号分隔",
"constraints": "用户明确提出的边界,多项用分号分隔",
"deliverables": "希望得到的产物,多项用分号分隔",
"acceptanceCriteria": "用户可核验的完成标准,多项用分号分隔",
"horizon": "任务的时间范围或阶段",
"selectedAngleIds": ["请求中提供的角度ID"]
}
```
````
字段名必须逐字一致;`selectedAngleIds` 是字符串数组,其余字段都是字符串;代码块闭合后停止输出。无法确认但需要保留的假设,应在 `detail` 中以“暂定假设”小节明确写出,不得增加与前端不一致的自定义 JSON 字段。不得在任务草稿阶段直接给出候选策略。
## 安全与中立边界
- 对台海及其他敏感地缘议题,使用中性、可核验、降级风险的语言,区分事实、各方主张和分析推断。
- 禁止提供作战战术、目标选择、武器运用、规避侦测或利用具体脆弱点的可执行指导。
- 禁止设计针对特定人群的隐蔽操纵、欺骗、恐吓或定向政治说服;可将相关诉求重构为透明公共沟通、事实核查和社会韧性任务。
- 若原始诉求越过上述边界,保留其合法的高层目标,并把输出边界写入 `constraints`,例如“仅讨论外交、经济、法律、公共安全和危机降级选项”。
## 禁止事项
- 不生成完整策略或方案。
- 不替评判智能体给候选项打分。
- 不编造时间、预算、授权、数据或利益相关方立场。
- 不输出除 `[INTENT_READY]` 契约以外的自定义结构化字段名。
@@ -0,0 +1,6 @@
id: strategy-selection-intent
name: 策略优选·意图理解
description: 将用户的策略议题通过必要的简短澄清整理为任务名称、任务详情、前置条件、目标、约束、预期产物和建议分析角度;不直接生成策略。
tool_groups: []
skills:
- intent-clarification-policy
@@ -0,0 +1,65 @@
# 策略优选·智能评判智能体
你是策略优选流程的独立评判智能体。输入包含已确认的任务草稿,以及若干带稳定 `agentId`、角度名称和正文的候选策略。你只做比较、校验、评分和排序,不另造候选策略,不因为文风华丽而抬高得分。
## 评判流程
1. 先检查每个候选项是否真正回应任务目标、前置条件和硬约束。
2. 区分候选项中的事实、推断和建议;无法追溯的关键事实降低证据分。
3. 检查候选策略之间的重复、互补、冲突和前后依赖。
4. 按统一量表独立评分,再给出横向比较和推荐组合。
5. 只使用输入中的 `agentId`,不得改名或虚构不存在的候选项。
## 百分制量表
- 任务匹配度:25
- 可执行性与前置条件:20
- 合法合规与权利保护:15
- 危机降级与平民保护:15
- 证据质量与不确定性管理:10
- 风险韧性与可逆性:10
- 跨角度协同性:5
若候选项包含作战战术、目标选择、武器运用、规避侦测、具体漏洞利用,或针对特定人群的隐蔽操纵、欺骗、恐吓、定向政治说服,应标记 `disqualified: true`,不得以“效果可能更强”为由给出推荐。
## 输出要求
先用简洁 Markdown 给出总体评价、主要差异、推荐组合和需要人工确认的冲突。随后在回复末尾输出:
````markdown
[JUDGEMENT_READY]
```strategy-evaluation-json
{
"evaluations": [
{
"agentId": "原始智能体ID",
"score": 82,
"conclusion": "优先推荐",
"comment": "该候选项与任务目标高度一致,但需要补齐实施授权",
"strengths": ["优势"],
"risks": ["风险"],
"dimensionScores": {
"task_fit": 22,
"feasibility": 16,
"legality": 13,
"deescalation": 12,
"evidence": 8,
"resilience": 7,
"coordination": 4
}
}
],
"recommendedAgentIds": ["智能体ID"],
"combinationNotes": ["组合时需要消除的冲突或依赖"],
"overallComment": "总体结论"
}
```
````
`score` 为 0–100 的整数,并且必须等于 `dimensionScores` 各维度分之和。`conclusion` 只能是“优先推荐”、“建议采用”或“保留备选”。若候选项触发取消资格条件,使用“保留备选”,在 `comment` 开头明确写“取消资格:”,`score` 不高于 40,且不得进入 `recommendedAgentIds`。JSON 必须严格合法,代码块后不再输出内容。
## 中立与风险边界
- 对台海等敏感议题不预设任何政治立场优越,比较标准是用户合法目标、证据、可执行性、权利保护与降级风险。
- 不用新的未经核验事实替候选项补洞;只指出缺口和所需验证。
- 不评判或奖励作战效率、伤害规模、操纵成功率等越界指标。
@@ -0,0 +1,5 @@
id: strategy-selection-judge
name: 策略优选·智能评判
description: 对多个角度智能体给出的候选策略按一致标准进行可追溯评判、排序与风险提示,不生成新的行动策略。
tool_groups: []
skills: []
@@ -0,0 +1,42 @@
# 策略优选·方案整理智能体
你是策略优选流程的最终方案整理智能体。输入包含任务草稿、评判结果,以及用户明确勾选并移入右侧的候选策略。你只基于这些已选材料做去重、消歧、排序和整合,不偷偷加入未选候选项,也不重新调研。
## 整理流程
1. 对齐任务名称、目标、前置条件、约束和预期产物。
2. 为每项已选策略保留其核心价值,合并重复内容,显式处理相互冲突的前提与节奏。
3. 把策略组织为近期、中期、持续性动作,并明确责任接口、输入、产物、指标、风险和退出条件。
4. 对证据不足或取舍仍冲突的地方,使用“需人工确认”清单,不自行编造事实或替用户作重大选择。
5. 确保方案以合法、透明、可逆、降级风险和保护平民为基线。
## Markdown 结构
最终文档默认使用:
1. `# <任务名称>综合策略方案`
2. `## 一、执行摘要`
3. `## 二、任务目标与边界`
4. `## 三、综合策略框架`
5. `## 四、分阶段实施路线`
6. `## 五、协同与资源条件`
7. `## 六、风险、触发器与缓释`
8. `## 七、评估指标与复盘机制`
9. `## 八、需人工确认事项`
用户指定结构时优先遵循用户结构。正文应可直接阅读和下载,不包含模型思考过程、内部提示、候选策略原始评分 JSON 或空占位。
## 文件交付
当 `write_file` 可用时,用一次调用把完整正文写入:
`/mnt/user-data/outputs/综合策略方案.md`
不得用脚本生成文件,不得拆成多个文件。写入后在聊天正文中同步输出完整 Markdown,方便前端即时展示;若运行环境禁止写文件,仍须完整输出正文,由策略会话服务持久化和导出。
## 不可越过的边界
- 禁止补写作战战术、兵力部署、目标选择、打击时序、武器运用、规避侦测或具体漏洞利用。
- 禁止设计针对特定个人或群体的隐蔽操纵、欺骗、恐吓、微定向政治广告或定向政治说服。
- 对台海等敏感议题保持中立,区分事实、各方主张与分析推断,优先危机沟通、和平解决、人道保护和社会经济韧性。
- 若已选材料含越界内容,剔除可操作细节并在“风险与边界”中说明改为合法、非暴力、降级导向的替代方案。
@@ -0,0 +1,6 @@
id: strategy-selection-solution
name: 策略优选·方案整理
description: 将用户勾选的候选策略和评判意见去重、消歧并整理为一份完整的 Markdown 综合策略方案。
tool_groups:
- file:write
skills: []
@@ -4,7 +4,9 @@ from __future__ import annotations
import asyncio
import logging
import os
import shutil
import tempfile
import time
from datetime import datetime
from typing import Any
@@ -15,7 +17,10 @@ from fastapi import APIRouter, Depends, HTTPException, Query, Request
from pydantic import BaseModel, Field
from app.gateway.auth.password import verify_password_async
from app.gateway.deps import get_agent_store, get_config, get_tag_store
from app.gateway.deps import get_agent_store, get_config, get_skill_store, get_tag_store
from app.gateway.routers._strategy_selection_seed import (
STRATEGY_AGENT_ID_PREFIX,
)
from deerflow.agents.lead_agent.prompt import refresh_skills_system_prompt_cache_async
from deerflow.config.agents_api_config import get_agents_api_config
from deerflow.config.agents_config import CommonQuestion, list_custom_agents, load_agent_config, load_agent_soul, validate_agent_id
@@ -23,15 +28,39 @@ from deerflow.config.app_config import AppConfig
from deerflow.config.paths import get_paths
from deerflow.config.system_settings import load_system_settings, normalize_square_id, resolve_default_square_id
from deerflow.persistence.agents import AgentStore
from deerflow.persistence.skills import SkillStore
from deerflow.persistence.tags import TagStore
from deerflow.runtime.user_context import get_effective_user_id
from deerflow.skills.cascade import sync_agent_skills_to_available
from deerflow.skills.storage import get_or_new_skill_storage
from deerflow.skills.types import SkillCategory
from deerflow.skills.usage import all_entries as get_skill_usage_entries
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api", tags=["agents"])
def _is_strategy_agent_id(agent_id: str) -> bool:
return agent_id.casefold().startswith(STRATEGY_AGENT_ID_PREFIX.casefold())
def _require_canonical_record_id(requested_id: str, record: dict[str, Any]) -> str:
"""Reject case-insensitive database aliases before touching agent files.
MySQL deployments may use a case-insensitive collation while Windows agent
directories are also case-insensitive. A lookup for a differently-cased
id must never be allowed to select one row and mutate another path.
"""
canonical_id = str(record.get("id") or "")
if canonical_id != requested_id:
raise HTTPException(
status_code=409,
detail=f"Agent id casing mismatch; use canonical id '{canonical_id}'",
)
return canonical_id
class AgentResponse(BaseModel):
"""Response model for an agent."""
@@ -276,6 +305,108 @@ def _validate_storage_id(agent_id: str) -> str:
raise HTTPException(status_code=422, detail=str(exc)) from exc
def _validate_strategy_agent_model(
raw_model: str | None,
*,
app_config: AppConfig,
) -> str | None:
"""Normalize a shared strategy role's model and reject stale names."""
model = (raw_model or "").strip() or None
if model is None:
return None
if model not in {entry.name for entry in app_config.models}:
raise HTTPException(
status_code=422,
detail=f"Unknown strategy agent model: {model}",
)
return model
async def _validate_strategy_agent_skills(
requested_skills: list[str] | None,
*,
app_config: AppConfig,
skill_store: SkillStore,
) -> list[str] | None:
"""Validate a global strategy role's skill allowlist.
Strategy-selection agents are built-in roles shared by every project and
every user. Their allowlists may therefore reference only canonical skill
names that exist on disk, are enabled/active, and are globally visible:
deployment-owned public skills, explicit built-in rows, or custom skills
currently published by their owner. In particular, an administrator must
not be able to attach a different user's unpublished skill merely because
``?admin=true`` exposes it in the management catalog.
"""
if requested_skills is None:
return None
normalized: list[str] = []
for raw_name in requested_skills:
name = raw_name.strip()
if not name:
raise HTTPException(
status_code=422,
detail="Strategy agent skill names cannot be blank",
)
if name not in normalized:
normalized.append(name)
try:
skills = get_or_new_skill_storage(app_config=app_config).load_skills(enabled_only=False)
ownership = {str(record.get("name") or ""): record for record in await skill_store.list_all() if record.get("name")}
usage_entries = get_skill_usage_entries()
except HTTPException:
raise
except Exception as exc: # noqa: BLE001 - stable API response
logger.exception("Failed to validate strategy-agent skill allowlist")
raise HTTPException(status_code=503, detail="Skill catalog is unavailable") from exc
by_name = {skill.name: skill for skill in skills}
unknown = [name for name in normalized if name not in by_name]
if unknown:
raise HTTPException(
status_code=422,
detail=f"Unknown strategy agent skills: {', '.join(unknown)}",
)
unavailable = [name for name in normalized if not by_name[name].enabled or str((usage_entries.get(name) or {}).get("state") or "active") != "active"]
if unavailable:
raise HTTPException(
status_code=422,
detail=f"Disabled or archived strategy agent skills: {', '.join(unavailable)}",
)
not_global: list[str] = []
for name in normalized:
skill = by_name[name]
if skill.category != SkillCategory.CUSTOM:
continue
record = ownership.get(name)
if record is not None and (record.get("owner_user_id") is None or bool(record.get("published"))):
continue
not_global.append(name)
if not_global:
raise HTTPException(
status_code=422,
detail=(f"Strategy agent skills must be globally available; unpublished or unregistered custom skills: {', '.join(not_global)}"),
)
return normalized
def _ensure_strategy_agent_deletable(agent_id: str) -> None:
"""Keep fixed strategy role ids alive; their SOUL/skills remain editable."""
if _is_strategy_agent_id(agent_id):
raise HTTPException(
status_code=409,
detail=(f"Strategy role agent '{agent_id}' cannot be deleted; edit its SOUL and skills instead"),
)
def _write_agent_config(
agent_id: str,
*,
@@ -307,24 +438,19 @@ def _write_agent_config(
# Persist as plain dicts (dropping blank rows) so config.yaml stays a
# clean mapping rather than a pydantic repr. Accepts already-coerced
# CommonQuestion models or raw dicts/strings.
normalized = [
q if isinstance(q, CommonQuestion) else CommonQuestion.model_validate(q)
for q in common_questions
]
config_data["common_questions"] = [
q.model_dump() for q in normalized if q.prompt.strip()
]
normalized = [q if isinstance(q, CommonQuestion) else CommonQuestion.model_validate(q) for q in common_questions]
config_data["common_questions"] = [q.model_dump() for q in normalized if q.prompt.strip()]
if template_name is not None and template_name.strip():
config_data["template_name"] = template_name.strip()
# 会商席位技能识别强化开关:仅当显式设置时写入(None = 不写, 由 AgentConfig 默认为关)。
if seat_skill_directive is not None:
config_data["seat_skill_directive"] = bool(seat_skill_directive)
if llmwiki_knowledge_base_ids is not None:
config_data["llmwiki_knowledge_base_ids"] = list(
dict.fromkeys(item.strip() for item in llmwiki_knowledge_base_ids if item.strip())
)
with open(config_file, "w", encoding="utf-8") as f:
yaml.dump(config_data, f, default_flow_style=False, allow_unicode=True)
config_data["llmwiki_knowledge_base_ids"] = list(dict.fromkeys(item.strip() for item in llmwiki_knowledge_base_ids if item.strip()))
_atomic_write_text(
config_file,
yaml.safe_dump(config_data, default_flow_style=False, allow_unicode=True),
)
def _load_config_extras(agent_id: str) -> dict[str, Any]:
@@ -358,7 +484,35 @@ def _load_config_extras(agent_id: str) -> dict[str, Any]:
def _write_agent_soul(agent_id: str, soul: str) -> None:
agent_dir = get_paths().agent_dir(agent_id)
agent_dir.mkdir(parents=True, exist_ok=True)
(agent_dir / "SOUL.md").write_text(soul, encoding="utf-8")
_atomic_write_text(agent_dir / "SOUL.md", soul)
def _atomic_write_text(path, content: str) -> None:
"""Durably replace one small agent config file on the same filesystem."""
path.parent.mkdir(parents=True, exist_ok=True)
temp_name: str | None = None
try:
with tempfile.NamedTemporaryFile(
mode="w",
encoding="utf-8",
dir=path.parent,
prefix=f".{path.name}.",
suffix=".tmp",
delete=False,
) as handle:
temp_name = handle.name
handle.write(content)
handle.flush()
os.fsync(handle.fileno())
os.replace(temp_name, path)
temp_name = None
finally:
if temp_name is not None:
try:
os.unlink(temp_name)
except FileNotFoundError:
pass
async def _sync_legacy_agents(store: AgentStore) -> None:
@@ -413,11 +567,7 @@ async def _backfill_listing_cache(store: AgentStore, pairs: list[tuple[str, Any]
existing = cached.get(agent_id)
if existing is None or existing.get("skills") != want_skills:
await store.replace_skills(agent_id, want_skills)
if (
existing is None
or existing.get("tool_groups") != want_tool_groups
or existing.get("model") != want_model
):
if existing is None or existing.get("tool_groups") != want_tool_groups or existing.get("model") != want_model:
await store.set_extras(agent_id, tool_groups=want_tool_groups, model=want_model)
@@ -631,9 +781,7 @@ async def _build_list_responses(
SOUL.md is skipped (only the edit dialog reads it). An agent absent from
the cache (never mirrored) keeps its ``None`` extras until the next sync.
"""
responses = [
_record_to_response(a, include_soul=False, include_extras=False) for a in records
]
responses = [_record_to_response(a, include_soul=False, include_extras=False) for a in records]
ids = [r.id for r in responses]
extras = await store.get_extras_for(ids)
assignments = await tag_store.list_assignments("agent", ids)
@@ -686,11 +834,7 @@ async def list_agents(
),
admin: bool = Query(
default=False,
description=(
"Admin-only override. When ``true`` and the caller is a system admin, "
"every agent is returned (built-in + every user's agents + private-square "
"entries) regardless of the usual ownership/visibility filter."
),
description=("Admin-only override. When ``true`` and the caller is a system admin, every agent is returned (built-in + every user's agents + private-square entries) regardless of the usual ownership/visibility filter."),
),
) -> AgentsListResponse:
_require_agents_api_enabled()
@@ -744,11 +888,7 @@ async def list_agents(
if owner and owner.strip():
responses = [r for r in responses if r.user_id == owner.strip()]
if square_id:
responses = [
r
for r in responses
if (r.square_id or "") == square_id or (square_is_default and not (r.square_id or ""))
]
responses = [r for r in responses if (r.square_id or "") == square_id or (square_is_default and not (r.square_id or ""))]
responses = _sort_agent_responses(responses, sort)
return AgentsListResponse(agents=responses, total=len(responses), page=1, page_size=len(responses))
except HTTPException:
@@ -773,11 +913,7 @@ async def check_agent_name(name: str) -> dict[str, Any]:
"/agents/selector",
response_model=AgentSelectorResponse,
summary="Agent Homepage Selector",
description=(
"Return the admin-curated agent list shown on the new-chat homepage. "
"Sorted by ``featured_order`` ascending. Visibility-filtered, so an "
"agent the caller can't see (author un-published) is silently omitted."
),
description=("Return the admin-curated agent list shown on the new-chat homepage. Sorted by ``featured_order`` ascending. Visibility-filtered, so an agent the caller can't see (author un-published) is silently omitted."),
)
async def get_agent_selector(request: Request) -> AgentSelectorResponse:
_require_agents_api_enabled()
@@ -789,12 +925,7 @@ async def get_agent_selector(request: Request) -> AgentSelectorResponse:
records = await store.list_featured(user_id)
# Selector dropdown only renders name/description/featured_order — same
# rationale as list_agents: skip soul + extras + self-heal.
return AgentSelectorResponse(
agents=[
_record_to_response(r, include_soul=False, include_extras=False)
for r in records
]
)
return AgentSelectorResponse(agents=[_record_to_response(r, include_soul=False, include_extras=False) for r in records])
except HTTPException:
raise
except Exception as e:
@@ -853,6 +984,11 @@ async def create_agent_endpoint(request: AgentCreateRequest, http_request: Reque
if request.id:
agent_id = _validate_storage_id(request.id)
if _is_strategy_agent_id(agent_id):
raise HTTPException(
status_code=409,
detail=("The 'strategy-selection-' id namespace is reserved; create strategy angle agents through /api/strategy-agents/angles"),
)
if await store.get_any(agent_id) is not None:
raise HTTPException(status_code=409, detail=f"Agent id '{agent_id}' already exists")
else:
@@ -918,14 +1054,18 @@ async def create_agent_endpoint(request: AgentCreateRequest, http_request: Reque
async def update_agent(agent_id: str, request: AgentUpdateRequest, http_request: Request) -> AgentResponse:
_require_agents_api_enabled()
agent_id = _validate_storage_id(agent_id)
if _is_strategy_agent_id(agent_id):
raise HTTPException(
status_code=409,
detail=("Strategy agent configuration must be changed through /api/strategy-agents/{agent_id}"),
)
try:
store = get_agent_store(http_request)
user_id = _current_user_id(http_request)
is_admin = _is_admin_user(http_request)
current, edit_mode = await _get_editable_or_raise(
store, agent_id, user_id, is_admin=is_admin
)
current, edit_mode = await _get_editable_or_raise(store, agent_id, user_id, is_admin=is_admin)
_require_canonical_record_id(agent_id, current)
fields_set = request.model_fields_set
update_data: dict[str, Any] = {}
@@ -953,17 +1093,26 @@ async def update_agent(agent_id: str, request: AgentUpdateRequest, http_request:
next_description = update_data.get("description", current.get("description") or "")
existing_extras = _load_config_extras(agent_id)
next_skills = request.skills if "skills" in fields_set else existing_extras["skills"]
next_model = request.model if "model" in fields_set else existing_extras["model"]
if "skills" in fields_set and _is_strategy_agent_id(agent_id):
next_skills = await _validate_strategy_agent_skills(
request.skills,
app_config=get_config(http_request),
skill_store=get_skill_store(http_request),
)
else:
next_skills = request.skills if "skills" in fields_set else existing_extras["skills"]
if "model" in fields_set and _is_strategy_agent_id(agent_id):
next_model = _validate_strategy_agent_model(
request.model,
app_config=get_config(http_request),
)
else:
next_model = request.model if "model" in fields_set else existing_extras["model"]
next_tool_groups = request.tool_groups if "tool_groups" in fields_set else existing_extras["tool_groups"]
next_common_questions = request.common_questions if "common_questions" in fields_set else existing_extras["common_questions"]
next_template_name = request.template_name if "template_name" in fields_set else existing_extras["template_name"]
next_seat_skill_directive = request.seat_skill_directive if "seat_skill_directive" in fields_set else existing_extras["seat_skill_directive"]
next_llmwiki_ids = (
await _validate_llmwiki_bindings(http_request, request.llmwiki_knowledge_base_ids)
if "llmwiki_knowledge_base_ids" in fields_set
else existing_extras["llmwiki_knowledge_base_ids"]
)
next_llmwiki_ids = await _validate_llmwiki_bindings(http_request, request.llmwiki_knowledge_base_ids) if "llmwiki_knowledge_base_ids" in fields_set else existing_extras["llmwiki_knowledge_base_ids"]
config_dirty = bool(update_data) or any(key in fields_set for key in ("skills", "model", "tool_groups", "common_questions", "template_name", "seat_skill_directive", "llmwiki_knowledge_base_ids"))
if config_dirty:
@@ -1071,14 +1220,19 @@ async def update_user_profile(request: UserProfileUpdateRequest) -> UserProfileR
async def delete_agent(agent_id: str, request: Request) -> None:
_require_agents_api_enabled()
agent_id = _validate_storage_id(agent_id)
if _is_strategy_agent_id(agent_id):
raise HTTPException(
status_code=409,
detail=("Strategy agents cannot be deleted through the generic API; use /api/strategy-agents/{agent_id} to disable an angle"),
)
try:
store = get_agent_store(request)
user_id = _current_user_id(request)
is_admin = _is_admin_user(request)
_, edit_mode = await _get_editable_or_raise(
store, agent_id, user_id, is_admin=is_admin
)
record, edit_mode = await _get_editable_or_raise(store, agent_id, user_id, is_admin=is_admin)
_require_canonical_record_id(agent_id, record)
_ensure_strategy_agent_deletable(agent_id)
if edit_mode == "admin":
deleted = await store.delete_any(agent_id)
@@ -1382,11 +1536,7 @@ class AgentFeaturedReorderRequest(BaseModel):
agent_ids: list[str] = Field(
default_factory=list,
description=(
"Featured agent ids in the desired top→bottom display order. Ids not "
"currently featured are silently skipped, so the client can send the "
"current visible order without first reconciling with the server."
),
description=("Featured agent ids in the desired top→bottom display order. Ids not currently featured are silently skipped, so the client can send the current visible order without first reconciling with the server."),
)
@@ -1394,11 +1544,7 @@ class AgentFeaturedReorderRequest(BaseModel):
"/agents/featured/order",
status_code=204,
summary="Reorder Featured Agents (admin)",
description=(
"Admin-only. Bulk-assign ``featured_order`` to each id in the order received "
"(``0`` is topmost). After this, the homepage selector renders agents in "
"exactly the supplied order. Ids not already featured are ignored."
),
description=("Admin-only. Bulk-assign ``featured_order`` to each id in the order received (``0`` is topmost). After this, the homepage selector renders agents in exactly the supplied order. Ids not already featured are ignored."),
)
async def reorder_featured_agents(
body: AgentFeaturedReorderRequest,
@@ -181,6 +181,7 @@ class KnowledgeBaseCreate(BaseModel):
description: str = Field(default="", max_length=2048)
type: Literal["document", "faq"] = "document"
wiki_enabled: bool = False
embedding_model_id: str | None = Field(default=None, min_length=1, max_length=255)
class KnowledgeBaseUpdate(BaseModel):
@@ -251,7 +252,9 @@ def _store(request: Request) -> LlmWikiStore:
def _schedule_local_wiki_sync(request: Request, mapping: dict[str, Any]) -> None:
service = getattr(request.app.state, "llmwiki_sync_service", None)
config = request.app.state.config.llmwiki.local_wiki_index
config = getattr(request.app.state, "llmwiki_effective_config", None)
if config is None:
config = request.app.state.config.llmwiki.local_wiki_index
if service is not None and config.enabled and config.auto_sync and mapping.get("wiki_index_enabled", True):
from app.gateway.llmwiki_index_scheduler import spawn_local_wiki_index_job
@@ -300,6 +303,74 @@ def _raise_upstream(exc: WeKnoraError) -> None:
raise HTTPException(status_code=status, detail=str(exc)) from None
def _embedding_model_view(source: dict[str, Any]) -> dict[str, Any] | None:
"""Return the small, credential-free model shape needed by the create dialog."""
if str(source.get("type") or "").strip().lower() != "embedding":
return None
model_id = str(source.get("id") or "").strip()
if not model_id:
return None
status = str(source.get("status") or "active").strip().lower() or "active"
explicitly_available = source.get("available")
available = (
bool(explicitly_available)
if isinstance(explicitly_available, bool)
else status in {"active", "available", "enabled", "ready"}
)
parameters = source.get("parameters") if isinstance(source.get("parameters"), dict) else {}
def safe_text(*keys: str) -> str:
for key in keys:
value = source.get(key)
if isinstance(value, (str, int, float)) and str(value).strip():
return str(value).strip()
return ""
nested_provider = parameters.get("provider")
provider = safe_text("provider", "provider_type")
if not provider and isinstance(nested_provider, str):
provider = nested_provider.strip()
if not provider:
provider = safe_text("source", "platform")
nested_model = parameters.get("model") or parameters.get("model_name")
model_name = safe_text("model_name", "model")
if not model_name and isinstance(nested_model, str):
model_name = nested_model.strip()
return {
"id": model_id,
"name": safe_text("display_name", "name", "model_name", "model") or model_name or model_id,
"model_name": model_name,
"provider": provider,
"status": status,
"is_default": source.get("is_default") is True,
"available": available,
}
async def _embedding_models(client: WeKnoraClient) -> list[dict[str, Any]]:
return [view for item in await client.list_models() if (view := _embedding_model_view(item)) is not None]
def _select_embedding_model(models: list[dict[str, Any]], requested_id: str | None) -> str:
available = [item for item in models if item["available"]]
if requested_id:
selected = next((item for item in models if item["id"] == requested_id), None)
if selected is None:
raise WeKnoraError("The selected WeKnora embedding model does not exist", status_code=400)
if not selected["available"]:
raise WeKnoraError("The selected WeKnora embedding model is unavailable", status_code=400)
return requested_id
selected = next((item for item in available if item["is_default"]), None) or next(iter(available), None)
if selected is None:
raise WeKnoraError(
"WeKnora has no available embedding model; configure one in WeKnora before creating a knowledge base",
status_code=400,
)
return str(selected["id"])
def _json_response(payload: Any, *, status_code: int = 200) -> Response:
return Response(
content=json.dumps(payload, ensure_ascii=False, separators=(",", ":")).encode("utf-8"),
@@ -309,7 +380,10 @@ def _json_response(payload: Any, *, status_code: int = 200) -> Response:
def _runtime_for_iframe_proxy(request: Request | None = None):
runtime = get_resolved_llmwiki_runtime(getattr(request.app.state, "config", None) if request is not None else None)
source_config = None
if request is not None:
source_config = getattr(request.app.state, "llmwiki_source_config", None)
runtime = get_resolved_llmwiki_runtime(source_config)
if not runtime.weknora_enabled:
raise HTTPException(status_code=409, detail="WeKnora mode is not enabled")
if not runtime.web_base_url:
@@ -2485,7 +2559,9 @@ async def get_llmwiki_runtime() -> dict[str, Any]:
@router.get("/api/system-settings/llmwiki")
async def get_llmwiki_settings(request: Request) -> dict[str, Any]:
await _require_admin(request)
app_config = request.app.state.config
from deerflow.config import get_app_config
app_config = get_app_config()
runtime = get_resolved_llmwiki_runtime(app_config)
return {
**_runtime_or_legacy(),
@@ -2508,6 +2584,9 @@ async def update_llmwiki_settings(request: Request, body: LlmWikiSettingsUpdate)
raise HTTPException(status_code=422, detail=str(exc)) from None
current = load_system_settings()
save_system_settings(current.model_copy(update={"llmwiki": override}))
from app.gateway.llmwiki_index_runtime import rebuild_local_wiki_index_runtime
await rebuild_local_wiki_index_runtime(request.app, force=True)
return _runtime_or_legacy()
@@ -2516,13 +2595,16 @@ async def reset_llmwiki_settings(request: Request) -> dict[str, Any]:
await _require_admin(request)
current = load_system_settings()
save_system_settings(current.model_copy(update={"llmwiki": LlmWikiRuntimeOverride()}))
from app.gateway.llmwiki_index_runtime import rebuild_local_wiki_index_runtime
await rebuild_local_wiki_index_runtime(request.app, force=True)
return _runtime_or_legacy()
@router.post("/api/system-settings/llmwiki/test")
async def test_llmwiki_connection(request: Request, body: LlmWikiConnectionTest) -> dict[str, Any]:
await _require_admin(request)
runtime = get_resolved_llmwiki_runtime(request.app.state.config)
runtime = get_resolved_llmwiki_runtime()
if body.api_base_url is not None:
try:
candidate = normalize_service_url(body.api_base_url)
@@ -2677,11 +2759,13 @@ def _public_local_index_summary(
state: dict[str, Any] | None,
) -> dict[str, Any]:
app_state = request.app.state
local_config = getattr(
getattr(getattr(app_state, "config", None), "llmwiki", None),
"local_wiki_index",
None,
)
local_config = getattr(app_state, "llmwiki_effective_config", None)
if local_config is None:
local_config = getattr(
getattr(getattr(app_state, "config", None), "llmwiki", None),
"local_wiki_index",
None,
)
enabled = bool(getattr(local_config, "enabled", False))
current = dict(state or {})
state_name = str(current.get("state") or "not_synced")
@@ -3000,6 +3084,21 @@ async def list_knowledge_bases(
return {"knowledge_bases": knowledge_bases}
@router.get("/api/llmwiki/embedding-models")
async def list_embedding_models(request: Request) -> dict[str, Any]:
"""List selectable WeKnora embedding models without exposing model secrets."""
await _actor(request)
try:
models = await _embedding_models(_client_or_503())
except WeKnoraError as exc:
_raise_upstream(exc)
available = [item for item in models if item["available"]]
default_model = next((item for item in available if item["is_default"]), None) or next(iter(available), None)
default_model_id = str(default_model["id"]) if default_model is not None else None
return {"models": models, "default_model_id": default_model_id}
@router.get("/api/llmwiki/agents/{agent_id}/knowledge-bases")
async def list_agent_knowledge_bases(request: Request, agent_id: str) -> dict[str, Any]:
"""Return the agent-bound bases still visible to the current DeerFlow user."""
@@ -3038,11 +3137,16 @@ async def create_knowledge_base(request: Request, body: KnowledgeBaseCreate) ->
if body.name.strip() == CONVERSATION_DEPOSIT_KB_NAME:
raise HTTPException(status_code=409, detail="对话沉淀是 cmzs 系统保留知识库")
try:
embedding_model_id = _select_embedding_model(
await _embedding_models(client),
body.embedding_model_id,
)
remote = await client.create_knowledge_base(
name=body.name.strip(),
description=body.description,
kb_type=body.type,
wiki_enabled=body.wiki_enabled,
embedding_model_id=embedding_model_id,
)
except WeKnoraError as exc:
_raise_upstream(exc)
@@ -13,6 +13,10 @@ from fastapi import APIRouter, File, Form, HTTPException, Query, Request, Upload
from pydantic import BaseModel, Field
from app.gateway.deps import get_optional_user_from_request
from app.gateway.llmwiki_index_runtime import (
local_encoder_runtime_status,
rebuild_local_wiki_index_runtime,
)
from app.gateway.llmwiki_index_scheduler import spawn_local_wiki_index_job
from deerflow.config.runtime_paths import resolve_path, runtime_home
from deerflow.config.system_settings import load_system_settings, save_system_settings
@@ -53,8 +57,8 @@ async def _actor(request: Request) -> tuple[str, bool]:
return str(user.id), getattr(user, "system_role", None) == "admin"
def _services(request: Request):
config = request.app.state.config.llmwiki.local_wiki_index
async def _services(request: Request):
config = await rebuild_local_wiki_index_runtime(request.app)
if not config.enabled:
raise HTTPException(status_code=409, detail={"code": "WIKI_INDEX_DISABLED", "message": "Local Wiki index is disabled"})
search = getattr(request.app.state, "llmwiki_vector_search", None)
@@ -65,12 +69,12 @@ def _services(request: Request):
def _local_encoder(request: Request):
config = request.app.state.config.llmwiki.local_wiki_index.embedding
embedding = getattr(request.app.state, "llmwiki_embedding", None)
if config.provider != "local":
effective = getattr(request.app.state, "llmwiki_effective_config", None)
if effective is None or effective.embedding.provider != "local":
raise HTTPException(status_code=409, detail={"code": "EMBEDDING_NOT_LOCAL", "message": "当前 embedding provider 不是 local"})
embedding = getattr(request.app.state, "llmwiki_embedding", None)
if embedding is None:
raise HTTPException(status_code=503, detail={"code": "LOCAL_ENCODER_UNAVAILABLE", "message": "本地编码器未配置或未启用"})
raise HTTPException(status_code=503, detail={"code": "LOCAL_ENCODER_UNAVAILABLE", "message": "本地编码器目录未配置、无效或尚未就绪"})
return embedding
@@ -107,33 +111,35 @@ def _copy_encoder_uploads(files: list[UploadFile], paths: list[str], staging: Pa
return total
def _activate_uploaded_encoder(staging: Path) -> Path:
model_root = (runtime_home() / "models").resolve()
def _activate_uploaded_encoder(staging: Path, model_revision: str) -> Path:
model_root = (runtime_home() / "models" / "bge-m3-revisions").resolve()
model_root.mkdir(parents=True, exist_ok=True)
active = (model_root / "bge-m3").resolve()
active = (model_root / model_revision).resolve()
if active.parent != model_root:
raise RuntimeError("编码器目标目录越界")
backup = (model_root / f".bge-m3-backup-{uuid4().hex}").resolve()
if active.exists():
active.replace(backup)
try:
staging.replace(active)
except Exception:
if backup.exists() and not active.exists():
backup.replace(active)
raise
if backup.exists():
shutil.rmtree(backup)
raise RuntimeError("编码器版本目录已存在")
staging.replace(active)
return active
async def _save_encoder_path(request: Request, path: Path) -> dict[str, object]:
embedding = _local_encoder(request)
async def _save_encoder_path(
request: Request,
path: Path,
*,
model_revision: str | None = None,
) -> dict[str, object]:
current = load_system_settings()
encoder_settings = current.local_wiki_encoder.model_copy(update={"model_path": str(path)})
encoder_settings = current.local_wiki_encoder.model_copy(
update={
"mode": "local",
"model_path": str(path),
"model_revision": model_revision or uuid4().hex,
}
)
save_system_settings(current.model_copy(update={"local_wiki_encoder": encoder_settings}))
await embedding.reset_local_encoder(model_path=str(path))
return embedding.local_encoder_status()
await rebuild_local_wiki_index_runtime(request.app, force=True)
return local_encoder_runtime_status(request.app)
@router.get("/local-encoder/status")
@@ -141,7 +147,8 @@ async def local_encoder_status(request: Request) -> dict[str, object]:
_, is_admin = await _actor(request)
if not is_admin:
raise HTTPException(status_code=403, detail="Administrator access required")
return _local_encoder(request).local_encoder_status()
await rebuild_local_wiki_index_runtime(request.app)
return local_encoder_runtime_status(request.app)
@router.post("/local-encoder/start", status_code=202)
@@ -149,8 +156,10 @@ async def start_local_encoder(request: Request) -> dict[str, object]:
_, is_admin = await _actor(request)
if not is_admin:
raise HTTPException(status_code=403, detail="Administrator access required")
await rebuild_local_wiki_index_runtime(request.app)
try:
return _local_encoder(request).start_local_encoder()
_local_encoder(request).start_local_encoder()
return local_encoder_runtime_status(request.app)
except ValueError as exc:
raise HTTPException(status_code=409, detail={"code": "LOCAL_ENCODER_START_REJECTED", "message": str(exc)}) from None
@@ -163,6 +172,20 @@ async def configure_local_encoder(request: Request, body: LocalEncoderConfigRequ
return await _save_encoder_path(request, _validated_encoder_path(body.model_path))
@router.post("/local-encoder/use-configured")
async def use_configured_encoder(request: Request) -> dict[str, object]:
"""Restore the embedding provider declared in config.yaml without restart."""
_, is_admin = await _actor(request)
if not is_admin:
raise HTTPException(status_code=403, detail="Administrator access required")
current = load_system_settings()
encoder_settings = current.local_wiki_encoder.model_copy(update={"mode": "configured"})
save_system_settings(current.model_copy(update={"local_wiki_encoder": encoder_settings}))
await rebuild_local_wiki_index_runtime(request.app, force=True)
return local_encoder_runtime_status(request.app)
@router.post("/local-encoder/upload")
async def upload_local_encoder(
request: Request,
@@ -191,9 +214,17 @@ async def upload_local_encoder(
try:
uploaded_bytes = await asyncio.to_thread(_copy_encoder_uploads, files, paths, staging)
_validated_encoder_path(str(staging))
await _local_encoder(request).reset_local_encoder()
active = await asyncio.to_thread(_activate_uploaded_encoder, staging)
status = await _save_encoder_path(request, active)
model_revision = uuid4().hex
active = await asyncio.to_thread(
_activate_uploaded_encoder,
staging,
model_revision,
)
status = await _save_encoder_path(
request,
active,
model_revision=model_revision,
)
return {**status, "uploaded_files": len(files), "uploaded_bytes": uploaded_bytes}
except HTTPException:
raise
@@ -224,7 +255,7 @@ async def _authorized_mappings(request: Request, mapping_ids: list[str]) -> tupl
@router.post("/wiki-vector-search")
async def wiki_vector_search(request: Request, body: WikiVectorSearchRequest) -> dict[str, Any]:
config, search, _ = _services(request)
config, search, _ = await _services(request)
if not config.internal_search_enabled:
raise HTTPException(status_code=409, detail={"code": "WIKI_INTERNAL_SEARCH_DISABLED", "message": "Local Wiki search is not enabled"})
rows, user_id, is_admin = await _authorized_mappings(request, body.knowledge_base_ids)
@@ -250,7 +281,7 @@ async def local_wiki_page(
include_provenance: bool = Query(default=False),
include_archived: bool = Query(default=False),
) -> dict[str, Any]:
_, _, index_store = _services(request)
_, _, index_store = await _services(request)
user_id, is_admin = await _actor(request)
mapping = await request.app.state.llmwiki_store.get_authorized(mapping_id, user_id, write=False, is_admin=is_admin)
if mapping is None:
@@ -292,7 +323,7 @@ async def wiki_index_status(request: Request) -> dict[str, Any]:
_, is_admin = await _actor(request)
if not is_admin:
raise HTTPException(status_code=403, detail="Administrator access required")
config = request.app.state.config.llmwiki.local_wiki_index
config = await rebuild_local_wiki_index_runtime(request.app)
index_store = getattr(request.app.state, "llmwiki_index_store", None)
if index_store is None:
raise HTTPException(status_code=503, detail={"code": "WIKI_INDEX_UNAVAILABLE"})
@@ -352,7 +383,7 @@ async def _run_one_sync(app, mapping: dict[str, Any], *, force: bool) -> None:
@router.post("/wiki-index/sync", status_code=202)
async def sync_wiki_index(request: Request, body: WikiIndexActionRequest) -> dict[str, Any]:
_services(request)
await _services(request)
_, is_admin = await _actor(request)
if not is_admin:
raise HTTPException(status_code=403, detail="Administrator access required")
@@ -363,7 +394,7 @@ async def sync_wiki_index(request: Request, body: WikiIndexActionRequest) -> dic
@router.post("/wiki-index/rebuild", status_code=202)
async def rebuild_wiki_index(request: Request, body: WikiIndexActionRequest) -> dict[str, Any]:
_, _, index_store = _services(request)
_, _, index_store = await _services(request)
_, is_admin = await _actor(request)
if not is_admin:
raise HTTPException(status_code=403, detail="Administrator access required")
@@ -388,6 +419,7 @@ async def rebuild_one_wiki_index(request: Request, mapping_id: str, reason: str
@router.get("/knowledge-bases/{mapping_id}/wiki-index-status")
async def knowledge_base_wiki_index_status(request: Request, mapping_id: str) -> dict[str, Any]:
config = await rebuild_local_wiki_index_runtime(request.app)
user_id, is_admin = await _actor(request)
mapping = await request.app.state.llmwiki_store.get_authorized(mapping_id, user_id, write=False, is_admin=is_admin)
if mapping is None:
@@ -430,7 +462,7 @@ async def knowledge_base_wiki_index_status(request: Request, mapping_id: str) ->
return {
**state,
"knowledge_base_id": mapping_id,
"local_index_enabled": bool(request.app.state.config.llmwiki.local_wiki_index.enabled),
"local_index_enabled": bool(config.enabled),
"wiki_index_enabled": mapping.get("wiki_index_enabled", True),
"fully_vectorized": fully_vectorized,
"retrieval_mode": "vector" if fully_vectorized else "wiki_api",
@@ -448,7 +480,7 @@ async def knowledge_base_wiki_index_status(request: Request, mapping_id: str) ->
@router.post("/knowledge-bases/{mapping_id}/vectorize", status_code=202)
async def vectorize_knowledge_base(request: Request, mapping_id: str) -> dict[str, Any]:
config = request.app.state.config.llmwiki.local_wiki_index
config = await rebuild_local_wiki_index_runtime(request.app)
if not config.enabled:
raise HTTPException(
status_code=409,
@@ -68,10 +68,14 @@ class TaskUpdateRequest(BaseModel):
brief: str | None = None
agents: list[TaskAgentSchema] | None = None
messages: list[dict[str, Any]] | None = None
# Optional optimistic-concurrency token. Legacy callers may omit it; the
# strategy-project workbench always sends the revision it loaded/saved.
expected_updated_at: datetime | None = None
class TaskEnsureRequest(BaseModel):
"""get-or-create:宿主传的 taskId 不固定,新 id 直接**初始化**一条空记录返回(不 404)。"""
id: str = Field(min_length=1, max_length=64)
title: str = Field(default="", max_length=512)
brief: str | None = None
@@ -162,12 +166,24 @@ async def update_task(request: Request, task_id: str, body: TaskUpdateRequest) -
store = _get_store(request)
user_id = _current_user_id(request)
fields = body.model_dump(exclude_unset=True)
expected_updated_at = fields.pop("expected_updated_at", None)
# Normalize agents (pydantic models) to plain dicts for JSON storage.
if "agents" in fields and fields["agents"] is not None:
fields["agents"] = [a if isinstance(a, dict) else a.model_dump() for a in body.agents or []]
row = await store.update_task(task_id, user_id, **fields)
row = await store.update_task(
task_id,
user_id,
expected_updated_at=expected_updated_at,
**fields,
)
if row is None:
raise HTTPException(status_code=404, detail="Task not found")
existing = await store.get_task(task_id, user_id)
if existing is None:
raise HTTPException(status_code=404, detail="Task not found")
raise HTTPException(
status_code=409,
detail="项目已在其他页面更新,请选择恢复本地草稿或使用服务器版本",
)
return TaskResponse(**row)
@@ -31,18 +31,21 @@ from __future__ import annotations
import asyncio
import json
import logging
from typing import Any, AsyncIterator
from collections.abc import AsyncIterator
from typing import Any
import httpx
from fastapi import APIRouter, Body, HTTPException, Request
from fastapi.responses import StreamingResponse
from pydantic import BaseModel, Field
from app.gateway.roundtable_model_fallback import is_llm_error_message, reason_text
from app.gateway.routers import agents as agents_router
from app.gateway.routers._strategy_selection_seed import STRATEGY_AGENT_ID_PREFIX
from app.gateway.routers.multi_agent import (
_ROUNDTABLE_THREAD_METADATA,
_auth_headers,
_create_thread,
_flatten_content,
_loopback_base,
_make_loopback_client,
_parse_last_messages,
@@ -50,7 +53,9 @@ from app.gateway.routers.multi_agent import (
_stream_upstream,
_validate_agent_id,
)
from deerflow.agents.roundtable_orchestrator.delivery import visible_seat_text
from deerflow.tools.builtins.clarification_utils import resolve_allow_multiple
from deerflow.utils.stream_text import InlineThinkTagFilter
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/parallel-agents", tags=["parallel-agents"])
@@ -58,6 +63,18 @@ router = APIRouter(prefix="/api/parallel-agents", tags=["parallel-agents"])
# Soft cap on parallel degree — protects remote model concurrency + sandbox.
MAX_PARALLEL_AGENTS = 8
# Strategy roles are expected to return a substantive task/strategy/evaluation,
# not merely punctuation or a broken provider placeholder. Counting Unicode
# alphanumerics keeps the check language-neutral while rejecting outputs such as
# a long run of "!!!", which otherwise look non-empty to the UI.
MIN_MEANINGFUL_CONTENT_CHARS = 20
def _has_substantive_content(content: str) -> bool:
visible = visible_seat_text(content)
return sum(character.isalnum() for character in visible) >= MIN_MEANINGFUL_CONTENT_CHARS
# 禁两类工具:①**写文件**(write_file / str_replace)—— 并行席位互相写文件会打架;
# ②**派活 / 脚本逃逸**(agent_orchestration / bash)—— 本面板里每个智能体只做自己那
# 份分析交付,绝不该扮演「总控」去调度别人。弱模型(deepseek 等)拿到带「总控 / 业务
@@ -66,10 +83,10 @@ MAX_PARALLEL_AGENTS = 8
# glob / bash 翻找派活脚本)。物理禁掉这两类即可根治。其余只读工具(ls / read_file /
# 检索)与 ask_clarification(协作卡片)保留:既不互相打架,又能正常出步骤条 / 要澄清。
_EXCLUDED_TOOLS: list[str] = [
"write_file", # 并行不互相写文件打架
"write_file", # 并行不互相写文件打架
"str_replace",
"agent_orchestration", # 子智能体不派活 / 不调度(防模仿总控)
"bash", # 禁跑脚本(防绕道脚本调内部接口模仿派活)
"bash", # 禁跑脚本(防绕道脚本调内部接口模仿派活)
]
@@ -105,25 +122,126 @@ async def issue_token(body: _TokenRequest) -> _TokenResponse:
# ── frame normalisation (mirrors multi-agent.ts) ─────────────────────────────
def _extract_ai_text(chunk: dict[str, Any]) -> str:
"""AI text delta from a ``messages-tuple`` chunk obj; "" when not AI text."""
def _extract_ai_stream_parts(chunk: dict[str, Any]) -> tuple[str, str]:
"""Return ``(answer, reasoning)`` deltas from one AI message chunk.
OpenAI-compatible providers do not agree on where displayable reasoning
lives. Most put it in ``additional_kwargs.reasoning_content`` (or the
legacy ``reasoning`` key), while a few return typed content blocks. Keep
that channel separate from the answer so the strategy workbench can show
progress without mixing internal trace text into the generated strategy.
Literal ``<think>`` blocks in the normal text channel are handled by the
per-agent :class:`InlineThinkTagFilter` in ``_consume_agent`` because tags
may be split across arbitrary SSE chunks.
"""
type_ = str(chunk.get("type") or "").lower()
if type_ not in ("ai", "aimessagechunk", "aimessage"):
return ""
return "", ""
content = chunk.get("content")
answer_parts: list[str] = []
reasoning_parts: list[str] = []
if isinstance(content, str):
return content
if isinstance(content, list):
out: list[str] = []
answer_parts.append(content)
elif isinstance(content, list):
for item in content:
if isinstance(item, str):
out.append(item)
answer_parts.append(item)
elif isinstance(item, dict):
t = item.get("text")
if isinstance(t, str):
out.append(t)
return "".join(out)
return ""
block_type = str(item.get("type") or "").lower()
value = item.get("thinking")
if not isinstance(value, str):
value = item.get("text")
if not isinstance(value, str):
value = item.get("content")
if not isinstance(value, str):
continue
if block_type in {
"thinking",
"thinking_delta",
"reasoning",
"reasoning_delta",
}:
reasoning_parts.append(value)
else:
answer_parts.append(value)
additional_kwargs = chunk.get("additional_kwargs")
direct_reasoning = chunk.get("reasoning_content") or chunk.get("reasoning")
nested_reasoning: object = None
if isinstance(additional_kwargs, dict):
nested_reasoning = additional_kwargs.get("reasoning_content") or additional_kwargs.get("reasoning")
raw_reasoning = nested_reasoning or direct_reasoning
if isinstance(raw_reasoning, str):
reasoning_parts.append(raw_reasoning)
return "".join(answer_parts), "".join(reasoning_parts)
def _extract_ai_text(chunk: dict[str, Any]) -> str:
"""Compatibility helper returning only the ordinary AI text delta."""
return _extract_ai_stream_parts(chunk)[0]
def _split_final_inline_reasoning(content: str) -> tuple[str, str]:
"""Split complete inline thinking, including template-injected close tags.
Some reasoning chat templates insert ``<think>`` before generation, so the
provider returns only ``reasoning</think>answer``. The streaming filter
cannot classify that prefix before the closing marker arrives, but the
terminal values frame can. Returning the recovered trace here also lets
the client correct any transient streaming classification.
"""
if not content:
return "", ""
working = content
prefix_reasoning = ""
lowered = working.lower()
first_open = lowered.find("<think>")
first_close = lowered.find("</think>")
if first_close >= 0 and (first_open < 0 or first_close < first_open):
prefix_reasoning = working[:first_close]
working = working[first_close + len("</think>") :]
text_filter = InlineThinkTagFilter()
visible, reasoning = text_filter.push_parts(working)
visible_tail, reasoning_tail = text_filter.finish_parts()
final_reasoning = "".join(part for part in (prefix_reasoning, reasoning, reasoning_tail) if part)
# ``visible_seat_text`` remains the canonical complete-output cleanup for
# malformed/multiple tags; the filter-derived visible value is only a
# fallback for an otherwise empty canonical result.
final_visible = visible_seat_text(content) or f"{visible}{visible_tail}".strip()
return final_visible, final_reasoning.strip()
def _should_probe_implicit_reasoning(
request: Request,
agent_id: str,
requested_model: str,
) -> bool:
"""Enable close-only probing only for a thinking-capable effective model.
Ordinary models must stream untagged answer chunks immediately. The
stricter prelude buffer is reserved for providers that advertise thinking
support and may use templates where ``<think>`` is injected outside the
returned content while ``</think>`` remains in-band.
"""
config = getattr(request.app.state, "config", None)
models = list(getattr(config, "models", None) or [])
effective_name = requested_model.strip()
if not effective_name:
try:
effective_name = str(agents_router._load_config_extras(agent_id).get("model") or "").strip()
except Exception:
effective_name = ""
if not effective_name and models:
effective_name = str(getattr(models[0], "name", "") or "")
selected = next(
(entry for entry in models if str(getattr(entry, "name", "") or "") == effective_name),
None,
)
return bool(selected and getattr(selected, "supports_thinking", False))
def _ingest_tool_chunks(chunks: Any, acc: dict[int, dict[str, Any]]) -> None:
@@ -231,7 +349,12 @@ async def _run_one_agent(
if isinstance(msg, dict) and (msg.get("type") or "").lower() in ("ai", "aimessage", "aimessagechunk"):
last_ai = msg
break
content = _flatten_content(last_ai.get("content", ""))
failure_reason = is_llm_error_message(last_ai)
if failure_reason:
raise RuntimeError(f"模型调用失败:{reason_text(failure_reason)}")
answer_channel, structured_reasoning = _extract_ai_stream_parts(last_ai)
content, inline_reasoning = _split_final_inline_reasoning(answer_channel)
reasoning = "\n\n".join(part.strip() for part in (structured_reasoning, inline_reasoning) if part.strip())
# 收集**所有** AI 消息的 tool_calls(全量 args,按顺序)—— 用于在收口时补发所有步骤
# (含 ls / skill_list 这类无参/中间步骤),保证步骤条不丢步、且 args 完整。
final_tool_calls: list[dict[str, Any]] = []
@@ -246,13 +369,17 @@ async def _run_one_agent(
yield {
"type": "clarification",
"content": content,
"reasoning": reasoning,
"clarification": clarification,
"tool_calls": final_tool_calls,
}
else:
if not _has_substantive_content(content):
raise RuntimeError("智能体未生成有效正文,请重试或更换全局模型")
yield {
"status": f"子智能体 {agent_id} 完成",
"content": content,
"reasoning": reasoning,
"agent_name": agent_id,
"tool_calls": final_tool_calls,
}
@@ -264,10 +391,7 @@ def _build_task_message(task_name: str, brief: str) -> str:
parts.append(f"任务名称:{task_name.strip()}")
if brief.strip():
parts.append(f"任务简介:\n{brief.strip()}")
parts.append(
"请你从你的专业职责出发,针对以上任务给出你的分析与交付。"
"本轮为**并行**研讨:请把你的产出**直接写在回复正文里**(本轮禁止写文件)。"
)
parts.append("请你从你的专业职责出发,针对以上任务给出你的分析与交付。本轮为**并行**研讨:请把你的产出**直接写在回复正文里**(本轮禁止写文件)。")
# 角色边界护栏:本面板里每个智能体都是**执行席位**,不是总控 / 指挥。即便任务里带有
# 「总控 / 业务链条 / 调度 / 派活」字样,也只完成属于自己的那份交付,严禁模仿总控派活。
parts.append(
@@ -310,6 +434,41 @@ async def run_parallel_agents_stream(request: Request, payload: dict = Body(...)
status_code=400,
detail=f"并行智能体数量上限 {MAX_PARALLEL_AGENTS}(当前 {len(agent_ids)})",
)
role_store = getattr(request.app.state, "strategy_agent_role_store", None)
agent_store = getattr(request.app.state, "agent_store", None)
strategy_ids = [agent_id for agent_id in agent_ids if agent_id.casefold().startswith(STRATEGY_AGENT_ID_PREFIX.casefold())]
if strategy_ids and role_store is not None and agent_store is not None:
# Every worker owns an independent memory store. Synchronize from
# durable folders/sidecars immediately before execution so a request
# routed to another worker cannot see random 404s or revived angles.
from app.gateway.routers.strategy_agents import _ensure_registry
await _ensure_registry(agent_store, role_store)
for agent_id in agent_ids:
if not agent_id.casefold().startswith(STRATEGY_AGENT_ID_PREFIX.casefold()):
continue
if role_store is None or agent_store is None:
raise HTTPException(
status_code=503,
detail="策略智能体分类或配置服务不可用",
)
role = await role_store.get_role(agent_id)
if role is None:
raise HTTPException(
status_code=400,
detail=f"未注册的策略智能体:{agent_id}",
)
if not bool(role.get("enabled")):
raise HTTPException(
status_code=409,
detail=f"策略智能体已停用:{agent_id}",
)
record = await agent_store.get_any(agent_id)
if record is None or str(record.get("id") or "") != agent_id or record.get("user_id") is not None:
raise HTTPException(
status_code=409,
detail=f"策略智能体必须由系统全局持有:{agent_id}",
)
if not task_name and not brief:
raise HTTPException(status_code=400, detail="任务名称与简介至少填写其一")
@@ -327,8 +486,54 @@ async def run_parallel_agents_stream(request: Request, payload: dict = Body(...)
emitted_tools: set[str] = set() # 已发过 step 的 tool_call id(去重)
tool_acc: dict[int, dict[str, Any]] = {} # tool_call_chunks 累积
buffer: list[str] = []
raw_answer_buffer: list[str] = []
probe_implicit_close = await asyncio.to_thread(
_should_probe_implicit_reasoning,
request,
agent_id,
model_name,
)
inline_thinking = InlineThinkTagFilter(allow_implicit_close=probe_implicit_close)
reasoning_emitted = False
done_sent = False
async def _emit_text_parts(text: str, provider_reasoning: str = "") -> None:
nonlocal reasoning_emitted
if text:
raw_answer_buffer.append(text)
visible_prelude = inline_thinking.confirm_visible_channel() if provider_reasoning else ""
visible, inline_reasoning = inline_thinking.push_parts(text)
reasoning = f"{provider_reasoning}{inline_reasoning}"
if reasoning:
reasoning_emitted = True
await queue.put(
{
"type": "reasoning_delta",
"agent_id": agent_id,
"text": reasoning,
}
)
confirmed_visible = f"{visible_prelude}{visible}"
if confirmed_visible:
buffer.append(confirmed_visible)
await queue.put({"type": "delta", "agent_id": agent_id, "text": confirmed_visible})
async def _flush_text_filter() -> None:
nonlocal reasoning_emitted
visible, reasoning = inline_thinking.finish_parts()
if reasoning:
reasoning_emitted = True
await queue.put(
{
"type": "reasoning_delta",
"agent_id": agent_id,
"text": reasoning,
}
)
if visible:
buffer.append(visible)
await queue.put({"type": "delta", "agent_id": agent_id, "text": visible})
async def _emit_tool(tc: Any, allow_empty: bool = False) -> None:
"""一个 tool_call(含完整 args)→ 一条 step 事件;按 id 去重。
@@ -350,9 +555,7 @@ async def run_parallel_agents_stream(request: Request, payload: dict = Body(...)
if key_id in emitted_tools:
return
emitted_tools.add(key_id)
await queue.put(
{"type": "step", "agent_id": agent_id, "key": f"tool_calling:{name}", "label": name, "args": args}
)
await queue.put({"type": "step", "agent_id": agent_id, "key": f"tool_calling:{name}", "label": name, "args": args})
try:
thread_id = await _create_thread(client, base, headers, metadata=_ROUNDTABLE_THREAD_METADATA)
@@ -362,22 +565,32 @@ async def run_parallel_agents_stream(request: Request, payload: dict = Body(...)
async for chunk in gen:
if isinstance(chunk, dict):
# 终态:先用最终 tool_calls(全量 args)补发漏掉的 step,再发收口/澄清。
await _flush_text_filter()
for tc in chunk.get("tool_calls") or []:
await _emit_tool(tc, allow_empty=True)
final_content = visible_seat_text(str(chunk.get("content") or ""))
final_reasoning = str(chunk.get("reasoning") or "")
if final_reasoning and not reasoning_emitted:
reasoning_emitted = True
await queue.put(
{
"type": "reasoning_delta",
"agent_id": agent_id,
"text": final_reasoning,
}
)
if chunk.get("type") == "clarification":
clar = chunk.get("clarification") or {}
await queue.put(
{
"type": "agent_clarification",
"agent_id": agent_id,
"content": str(chunk.get("content") or ""),
"content": final_content,
**clar,
}
)
else:
await queue.put(
{"type": "agent_done", "agent_id": agent_id, "content": str(chunk.get("content") or "")}
)
await queue.put({"type": "agent_done", "agent_id": agent_id, "content": final_content})
done_sent = True
continue
line = chunk.strip() if isinstance(chunk, str) else ""
@@ -396,10 +609,9 @@ async def run_parallel_agents_stream(request: Request, payload: dict = Body(...)
if last_event == "messages" and isinstance(parsed, list) and parsed:
obj = parsed[0]
if isinstance(obj, dict):
text = _extract_ai_text(obj)
if text:
buffer.append(text)
await queue.put({"type": "delta", "agent_id": agent_id, "text": text})
text, reasoning = _extract_ai_stream_parts(obj)
if text or reasoning:
await _emit_text_parts(text, reasoning)
# 完整 tool_calls(部分模型直接给)+ 累积 chunks 后的合成调用,都尝试发 step。
for tc in obj.get("tool_calls") or []:
await _emit_tool(tc)
@@ -408,8 +620,30 @@ async def run_parallel_agents_stream(request: Request, payload: dict = Body(...)
await _emit_tool(tc)
if not done_sent:
# 流被抢占/截断,没收到终态帧 —— 用已累积正文兜底收口本席位。
await _flush_text_filter()
buffered_content, recovered_reasoning = _split_final_inline_reasoning("".join(raw_answer_buffer))
if not buffered_content:
buffered_content = "".join(buffer)
if recovered_reasoning and not reasoning_emitted:
reasoning_emitted = True
await queue.put(
{
"type": "reasoning_delta",
"agent_id": agent_id,
"text": recovered_reasoning,
}
)
failure_reason = is_llm_error_message({"type": "ai", "content": buffered_content})
if failure_reason:
raise RuntimeError(f"模型调用失败:{reason_text(failure_reason)}")
if not _has_substantive_content(buffered_content):
raise RuntimeError("智能体未生成有效正文,请重试或更换全局模型")
await queue.put(
{"type": "agent_done", "agent_id": agent_id, "content": "".join(buffer)}
{
"type": "agent_done",
"agent_id": agent_id,
"content": buffered_content,
}
)
except Exception as exc: # noqa: BLE001 — 单个 agent 失败不拖垮其它
logger.warning("[parallel-agents] %s failed: %r", agent_id, exc)
@@ -71,6 +71,10 @@ class ChainSeatSchema(BaseModel):
# 岗位协同专用的席位岗位归属。字段保存在既有 seats JSON 中,普通圆桌编排
# 忽略它;显式声明可确保 Pydantic 在 create/update 的 model_dump() 时不剥掉。
position_id: str | None = Field(default=None, max_length=64)
# 该席位提交过程产物时传给外部任务系统的 position 值(8BF 会商页用)。
# 缺省 None = 提交时回退 0。保存在既有 seats JSON 中,无需迁移;显式声明
# 可确保 Pydantic 在 create/update 的 model_dump() 时不剥掉。
artifact_position: int | None = None
# 该席位在业务链中的岗位职责。会商智能体配置面板只读展示此字段;
# 保存在既有 seats JSON 中,无需迁移。空/None = 未填写。
job_responsibilities: str | None = Field(default=None, max_length=4000)
@@ -0,0 +1,802 @@
"""Global strategy-selection agent role management.
The strategy workbench owns three fixed roles (intent, judge and solution)
plus an administrator-managed set of angle roles. Role metadata is stored in
``strategy_agent_roles`` while model/SOUL/skills remain in the normal
folder-backed agent configuration, so the same configuration is shared by
every project and every user.
"""
from __future__ import annotations
import asyncio
import logging
import os
import shutil
import weakref
from contextlib import asynccontextmanager
from datetime import datetime
from typing import Literal
from uuid import uuid4
import yaml
from fastapi import APIRouter, HTTPException, Request
from pydantic import BaseModel, Field
from app.gateway.auth.disabled_mode import is_auth_disabled
from app.gateway.deps import (
get_agent_store,
get_config,
get_current_user_from_request,
get_skill_store,
get_strategy_agent_role_store,
)
from app.gateway.routers import agents as agents_router
from app.gateway.routers._strategy_selection_seed import (
STRATEGY_ANGLE_AGENT_PREFIX,
default_strategy_agent_roles,
ensure_strategy_selection_agents,
)
from deerflow.config.paths import get_paths
from deerflow.persistence.agents import AgentStore
from deerflow.persistence.strategy_agent_roles import (
MemoryStrategyAgentRoleStore,
StrategyAgentRoleStore,
)
logger = logging.getLogger(__name__)
router = APIRouter(prefix="/api/strategy-agents", tags=["strategy-agents"])
StrategyAgentCategory = Literal["intent", "angle", "judge", "solution"]
_DYNAMIC_ANGLE_TOOL_GROUPS = ["web", "file:read"]
_ROLE_SIDECAR = ".strategy-role.yaml"
_PROCESS_LOCKS: weakref.WeakValueDictionary[str, asyncio.Lock] = weakref.WeakValueDictionary()
def _process_lock(agent_id: str) -> asyncio.Lock:
key = agent_id.casefold()
lock = _PROCESS_LOCKS.get(key)
if lock is None:
lock = asyncio.Lock()
_PROCESS_LOCKS[key] = lock
return lock
def _open_cross_process_lock(agent_id: str):
lock_dir = get_paths().agents_dir / ".strategy-locks"
lock_dir.mkdir(parents=True, exist_ok=True)
path = lock_dir / f"{agent_id}.lock"
handle = open(path, "a+b") # noqa: SIM115 - owned by async context below
if path.stat().st_size == 0:
handle.write(b"\0")
handle.flush()
return handle
def _try_cross_process_lock(handle) -> bool:
handle.seek(0)
try:
if os.name == "nt":
import msvcrt
msvcrt.locking(handle.fileno(), msvcrt.LK_NBLCK, 1)
else:
import fcntl
fcntl.flock(handle.fileno(), fcntl.LOCK_EX | fcntl.LOCK_NB)
return True
except OSError:
return False
def _release_cross_process_lock(handle) -> None:
try:
handle.seek(0)
if os.name == "nt":
import msvcrt
msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
else:
import fcntl
fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
finally:
handle.close()
@asynccontextmanager
async def _strategy_mutation_guard(agent_id: str):
"""Serialize one strategy agent across coroutines and worker processes.
The zero-byte lock-file namespace is durable, but OS locks are tied to the
open handle and are automatically released if a worker dies. The local
lock table uses weak values so one-off dynamic ids do not leak forever.
"""
async with _process_lock(agent_id):
handle = _open_cross_process_lock(agent_id)
acquired = False
try:
while not acquired:
acquired = _try_cross_process_lock(handle)
if not acquired:
await asyncio.sleep(0.05)
yield
finally:
if acquired:
# Unlock synchronously: this is a tiny OS call and must not be
# skipped if the request is already being cancelled.
_release_cross_process_lock(handle)
else:
handle.close()
def _write_role_sidecar(agent_id: str, role: dict) -> None:
payload = {
"agent_id": agent_id,
"category": "angle",
"fixed": False,
"enabled": bool(role.get("enabled", True)),
"sort_order": int(role.get("sort_order", 0)),
}
agents_router._atomic_write_text(
get_paths().agent_dir(agent_id) / _ROLE_SIDECAR,
yaml.safe_dump(payload, allow_unicode=True, sort_keys=False),
)
def _read_optional_text(path) -> str | None:
return path.read_text(encoding="utf-8") if path.is_file() else None
def _restore_optional_text(path, content: str | None) -> None:
if content is None:
path.unlink(missing_ok=True)
return
agents_router._atomic_write_text(path, content)
async def _rollback_strategy_update(
*,
agent_id: str,
agent_store: AgentStore,
role_store: StrategyAgentRoleStore,
record: dict,
role: dict,
extras: dict,
file_snapshot: dict,
) -> None:
"""Best-effort compensation for the mixed DB/filesystem update."""
try:
agent_dir = get_paths().agent_dir(agent_id)
await asyncio.to_thread(
_restore_optional_text,
agent_dir / "config.yaml",
file_snapshot["config"],
)
await asyncio.to_thread(
_restore_optional_text,
agent_dir / "SOUL.md",
file_snapshot["soul"],
)
await asyncio.to_thread(
_restore_optional_text,
agent_dir / _ROLE_SIDECAR,
file_snapshot["sidecar"],
)
await agent_store.update_any(
agent_id,
{
"name": record["name"],
"description": record.get("description") or "",
},
)
await agent_store.replace_skills(agent_id, extras["skills"])
await agent_store.set_extras(
agent_id,
tool_groups=extras["tool_groups"],
model=extras["model"],
)
await role_store.update_role(
agent_id,
enabled=bool(role["enabled"]),
sort_order=int(role["sort_order"]),
)
except Exception:
logger.exception("Failed to compensate strategy-agent update for '%s'", agent_id)
async def _recover_memory_angle_roles(role_store: StrategyAgentRoleStore) -> None:
"""Recover dynamic role metadata after a memory-mode process restart."""
if not isinstance(role_store, MemoryStrategyAgentRoleStore):
return
agents_dir = get_paths().agents_dir
if not agents_dir.is_dir():
return
for agent_dir in agents_dir.iterdir():
sidecar = agent_dir / _ROLE_SIDECAR
if not sidecar.is_file():
continue
try:
raw = yaml.safe_load(sidecar.read_text(encoding="utf-8")) or {}
agent_id = str(raw.get("agent_id") or "")
if agent_id != agent_dir.name or not agent_id.startswith(STRATEGY_ANGLE_AGENT_PREFIX) or raw.get("category") != "angle" or bool(raw.get("fixed", False)):
raise ValueError("invalid dynamic angle sidecar")
existing = await role_store.get_role(agent_id)
if existing is None:
await role_store.create_role(
{
"agent_id": agent_id,
"category": "angle",
"fixed": False,
"enabled": bool(raw.get("enabled", True)),
"sort_order": int(raw.get("sort_order", 0)),
}
)
elif not bool(existing.get("fixed")) and existing.get("category") == "angle":
# Memory stores are rebuilt with code defaults first. The
# sidecar is the durable authority for every non-fixed angle,
# including the six shipped angles, so disabled defaults do
# not silently revive after a worker restart.
await role_store.update_role(
agent_id,
enabled=bool(raw.get("enabled", True)),
sort_order=int(raw.get("sort_order", 0)),
)
except Exception:
logger.exception("Ignoring invalid strategy role sidecar at %s", sidecar)
def _default_angle_soul(name: str, description: str) -> str:
focus = description.strip() or "围绕任务目标,从本角度给出独立、可执行的策略建议"
return (
f"# 角色\n\n你是“{name}”,负责{focus}。\n\n"
"# 工作要求\n\n"
"1. 先核对任务目标、约束、前置条件和时间范围;信息不足时明确假设。\n"
"2. 只从自己的专业角度分析,不替代其他角度,也不冒充评判或方案整理角色。\n"
"3. 输出具体策略、实施步骤、预期收益、主要风险、触发条件和退出条件。\n"
"4. 对时效性事实优先检索核验并标注依据;不得编造来源。\n"
"5. 遵守法律、安全与非升级边界,最终交付使用清晰的 Markdown。\n"
)
class StrategyAgentItem(BaseModel):
id: str
category: StrategyAgentCategory
fixed: bool
enabled: bool
sort_order: int
name: str
description: str = ""
model: str | None = None
soul: str | None = None
skills: list[str] | None = None
created_at: datetime | str | None = None
updated_at: datetime | str | None = None
class StrategyAgentListResponse(BaseModel):
agents: list[StrategyAgentItem]
class StrategyAngleCreateRequest(BaseModel):
name: str = Field(min_length=1, max_length=100)
description: str = Field(default="", max_length=2000)
soul: str = Field(default="", max_length=200_000)
model: str | None = Field(default=None, max_length=200)
skills: list[str] = Field(default_factory=list, max_length=100)
sort_order: int | None = Field(default=None, ge=-10_000, le=10_000)
class StrategyAgentUpdateRequest(BaseModel):
name: str | None = Field(default=None, max_length=100)
description: str | None = Field(default=None, max_length=2000)
soul: str | None = Field(default=None, max_length=200_000)
model: str | None = Field(default=None, max_length=200)
skills: list[str] | None = Field(default=None, max_length=100)
enabled: bool | None = None
sort_order: int | None = Field(default=None, ge=-10_000, le=10_000)
async def _require_admin(request: Request) -> None:
"""Require an administrator, except in explicit auth-disabled mode."""
user = getattr(request.state, "user", None)
if user is None:
if is_auth_disabled():
return
user = await get_current_user_from_request(request)
if getattr(user, "system_role", None) != "admin":
raise HTTPException(status_code=403, detail="策略智能体管理仅限管理员")
def _normalize_model(request: Request, raw_model: str | None) -> str | None:
return agents_router._validate_strategy_agent_model(
raw_model,
app_config=get_config(request),
)
async def _ensure_registry(
agent_store: AgentStore,
role_store: StrategyAgentRoleStore,
) -> None:
"""Seed missing role metadata and repair missing default agent rows."""
defaults = default_strategy_agent_roles()
await role_store.ensure_defaults(defaults)
await _recover_memory_angle_roles(role_store)
default_ids = [str(row["agent_id"]) for row in defaults]
for agent_id in default_ids:
existing = await agent_store.get_any(agent_id)
if existing is not None and existing.get("user_id") is not None:
# Never let legacy sync's ensure_builtin semantics silently treat a
# user-owned collision as one of the fixed global roles.
raise HTTPException(
status_code=409,
detail=f"Reserved strategy agent '{agent_id}' is owned by a user",
)
roles = await role_store.list_roles(include_disabled=True)
missing = [str(role["agent_id"]) for role in roles if await agent_store.get_any(str(role["agent_id"])) is None]
if missing:
# This path is normally handled by lifespan. It also rebuilds the
# memory-mode agent table from durable dynamic-angle folders.
await asyncio.to_thread(ensure_strategy_selection_agents)
await agents_router._sync_legacy_agents(agent_store)
for role in roles:
agent_id = str(role["agent_id"])
record = await agent_store.get_any(agent_id)
if record is None:
raise HTTPException(
status_code=503,
detail=f"Strategy agent '{agent_id}' configuration is unavailable",
)
if str(record.get("id") or "") != agent_id or record.get("user_id") is not None:
raise HTTPException(
status_code=409,
detail=f"Strategy agent '{agent_id}' must be a canonical global agent",
)
async def ensure_strategy_agent_registry(app) -> None:
"""Synchronize one worker's registry, including memory-mode sidecars."""
agent_store = getattr(app.state, "agent_store", None)
role_store = getattr(app.state, "strategy_agent_role_store", None)
if agent_store is None or role_store is None:
raise RuntimeError("Strategy agent persistence is unavailable")
await _ensure_registry(agent_store, role_store)
async def _to_item(
role: dict,
record: dict,
*,
include_config: bool,
) -> StrategyAgentItem:
if include_config:
agent = await agents_router._record_to_response_async(
record,
include_soul=True,
include_extras=True,
)
return StrategyAgentItem(
id=agent.id,
category=role["category"],
fixed=bool(role["fixed"]),
enabled=bool(role["enabled"]),
sort_order=int(role["sort_order"]),
name=agent.name,
description=agent.description,
model=agent.model,
soul=agent.soul,
skills=agent.skills,
created_at=agent.created_at,
updated_at=agent.updated_at,
)
# Public consumers need only identity and lifecycle metadata. Avoid
# leaking prompts/model/skills and avoid synchronous filesystem reads.
return StrategyAgentItem(
id=str(record["id"]),
category=role["category"],
fixed=bool(role["fixed"]),
enabled=bool(role["enabled"]),
sort_order=int(role["sort_order"]),
name=str(record["name"]),
description=str(record.get("description") or ""),
created_at=record.get("created_at"),
updated_at=record.get("updated_at"),
)
async def _get_role_and_agent(
request: Request,
agent_id: str,
) -> tuple[dict, dict]:
role_store = get_strategy_agent_role_store(request)
agent_store = get_agent_store(request)
await _ensure_registry(agent_store, role_store)
role = await role_store.get_role(agent_id)
if role is None:
raise HTTPException(status_code=404, detail=f"Strategy agent '{agent_id}' not found")
record = await agent_store.get_any(agent_id)
if record is None:
raise HTTPException(
status_code=409,
detail=f"Strategy agent '{agent_id}' has no backing agent configuration",
)
if record.get("user_id") is not None:
raise HTTPException(
status_code=409,
detail=f"Strategy agent '{agent_id}' must be globally owned",
)
canonical_role_id = str(role.get("agent_id") or "")
if canonical_role_id != agent_id:
raise HTTPException(
status_code=409,
detail=(f"Strategy agent id casing mismatch; use canonical id '{canonical_role_id}'"),
)
agents_router._require_canonical_record_id(agent_id, record)
return role, record
@router.get("", response_model=StrategyAgentListResponse)
async def list_strategy_agents(
request: Request,
include_disabled: bool = False,
include_config: bool = False,
) -> StrategyAgentListResponse:
"""List the shared role catalog; sensitive configuration is admin-only."""
if include_disabled or include_config:
await _require_admin(request)
role_store = get_strategy_agent_role_store(request)
agent_store = get_agent_store(request)
await _ensure_registry(agent_store, role_store)
roles = await role_store.list_roles(include_disabled=include_disabled)
items: list[StrategyAgentItem] = []
for role in roles:
record = await agent_store.get_any(str(role["agent_id"]))
if record is None:
if bool(role["enabled"]):
raise HTTPException(
status_code=503,
detail=(f"Strategy agent '{role['agent_id']}' configuration is unavailable"),
)
continue
if str(record.get("id") or "") != str(role["agent_id"]) or record.get("user_id") is not None:
raise HTTPException(
status_code=409,
detail=f"Strategy agent '{role['agent_id']}' must be a canonical global agent",
)
items.append(await _to_item(role, record, include_config=include_config))
return StrategyAgentListResponse(agents=items)
@router.post(
"/angles",
response_model=StrategyAgentItem,
status_code=201,
)
async def create_strategy_angle(
payload: StrategyAngleCreateRequest,
request: Request,
) -> StrategyAgentItem:
"""Create one global angle agent. Fixed role categories are not creatable."""
await _require_admin(request)
name = agents_router._validate_display_name(payload.name)
model = _normalize_model(request, payload.model)
skills = await agents_router._validate_strategy_agent_skills(
payload.skills,
app_config=get_config(request),
skill_store=get_skill_store(request),
)
agent_store = get_agent_store(request)
role_store = get_strategy_agent_role_store(request)
await _ensure_registry(agent_store, role_store)
agent_id = f"{STRATEGY_ANGLE_AGENT_PREFIX}{uuid4().hex}"
# The generated id has already passed the fixed prefix/storage contract;
# all filesystem and persistence mutations happen under the cross-worker
# guard below.
agent_id = agents_router._validate_storage_id(agent_id)
async with _strategy_mutation_guard(agent_id):
return await _create_strategy_angle_locked(
agent_id=agent_id,
payload=payload,
name=name,
model=model,
skills=skills,
agent_store=agent_store,
role_store=role_store,
)
async def _cleanup_failed_create(
agent_id: str,
agent_store: AgentStore,
role_store: StrategyAgentRoleStore,
) -> None:
async def attempt(label: str, operation) -> None:
try:
result = operation()
if asyncio.iscoroutine(result):
await result
except BaseException: # cleanup must continue through cancellation/failures
logger.exception("Failed create cleanup step %s for '%s'", label, agent_id)
await attempt("role", lambda: role_store.delete_role(agent_id))
await attempt("agent", lambda: agent_store.delete_builtin(agent_id))
await attempt("extras", lambda: agent_store.delete_extras_for_agent(agent_id))
agent_dir = get_paths().agent_dir(agent_id)
if agent_dir.exists():
await attempt("folder", lambda: asyncio.to_thread(shutil.rmtree, agent_dir))
async def _create_strategy_angle_locked(
*,
agent_id: str,
payload: StrategyAngleCreateRequest,
name: str,
model: str | None,
skills: list[str] | None,
agent_store: AgentStore,
role_store: StrategyAgentRoleStore,
) -> StrategyAgentItem:
agent_dir = get_paths().agent_dir(agent_id)
if await agent_store.get_any(agent_id) is not None or agent_dir.exists():
# Cryptographically improbable, but never overwrite a folder if the
# deployment restored a row without its registry metadata.
raise HTTPException(status_code=409, detail="Generated strategy agent id already exists")
sort_order = payload.sort_order
if sort_order is None:
current = await role_store.list_roles(include_disabled=True)
angle_orders = [int(row["sort_order"]) for row in current if row.get("category") == "angle"]
sort_order = (max(angle_orders) + 1) if angle_orders else 100
soul = (
payload.soul
if payload.soul.strip()
else _default_angle_soul(
name,
payload.description,
)
)
completed = False
try:
await asyncio.to_thread(
agents_router._write_agent_config,
agent_id,
name=name,
description=payload.description,
skills=skills,
model=model,
tool_groups=_DYNAMIC_ANGLE_TOOL_GROUPS,
)
await asyncio.to_thread(agents_router._write_agent_soul, agent_id, soul)
record = await agent_store.ensure_builtin(
{
"id": agent_id,
"name": name,
"description": payload.description,
"published": True,
}
)
await agent_store.replace_skills(agent_id, skills)
await agent_store.set_extras(
agent_id,
tool_groups=_DYNAMIC_ANGLE_TOOL_GROUPS,
model=model,
)
role = await role_store.create_role(
{
"agent_id": agent_id,
"category": "angle",
"fixed": False,
"enabled": True,
"sort_order": sort_order,
}
)
await asyncio.to_thread(_write_role_sidecar, agent_id, role)
completed = True
return await _to_item(role, record, include_config=True)
except asyncio.CancelledError:
raise
except HTTPException:
raise
except Exception as exc:
logger.exception("Failed to create strategy angle agent '%s'", agent_id)
raise HTTPException(
status_code=500,
detail="Failed to create strategy angle agent",
) from exc
finally:
if not completed:
cleanup = asyncio.create_task(_cleanup_failed_create(agent_id, agent_store, role_store))
try:
await asyncio.shield(cleanup)
except asyncio.CancelledError:
# A second cancellation must not leave a half-created global
# agent behind while the file lock is released.
await cleanup
raise
@router.put("/{agent_id}", response_model=StrategyAgentItem)
async def update_strategy_agent(
agent_id: str,
payload: StrategyAgentUpdateRequest,
request: Request,
) -> StrategyAgentItem:
"""Update configuration; fixed roles cannot change lifecycle or category."""
await _require_admin(request)
agent_id = agents_router._validate_storage_id(agent_id)
async with _strategy_mutation_guard(agent_id):
return await _update_strategy_agent_locked(agent_id, payload, request)
async def _update_strategy_agent_locked(
agent_id: str,
payload: StrategyAgentUpdateRequest,
request: Request,
) -> StrategyAgentItem:
role, record = await _get_role_and_agent(request, agent_id)
agent_store = get_agent_store(request)
fields = payload.model_fields_set
if bool(role["fixed"]):
if "enabled" in fields and payload.enabled is not True:
raise HTTPException(status_code=409, detail="Fixed strategy roles cannot be disabled")
if "sort_order" in fields and payload.sort_order != int(role["sort_order"]):
raise HTTPException(status_code=409, detail="Fixed strategy role order cannot be changed")
next_name = agents_router._validate_display_name(payload.name or "") if "name" in fields else str(record["name"])
next_description = payload.description or "" if "description" in fields else str(record.get("description") or "")
extras = await asyncio.to_thread(agents_router._load_config_extras, agent_id)
next_model = _normalize_model(request, payload.model) if "model" in fields else extras["model"]
next_skills = (
await agents_router._validate_strategy_agent_skills(
payload.skills,
app_config=get_config(request),
skill_store=get_skill_store(request),
)
if "skills" in fields
else extras["skills"]
)
agent_dir = get_paths().agent_dir(agent_id)
file_snapshot = await asyncio.to_thread(
lambda: {
"config": _read_optional_text(agent_dir / "config.yaml"),
"soul": _read_optional_text(agent_dir / "SOUL.md"),
"sidecar": _read_optional_text(agent_dir / _ROLE_SIDECAR),
}
)
original_record = dict(record)
original_role = dict(role)
role_store = get_strategy_agent_role_store(request)
try:
config_fields = {"name", "description", "model", "skills"}
if fields & config_fields:
await asyncio.to_thread(
agents_router._write_agent_config,
agent_id,
name=next_name,
description=next_description,
skills=next_skills,
model=next_model,
tool_groups=extras["tool_groups"],
common_questions=extras["common_questions"],
template_name=extras["template_name"],
seat_skill_directive=extras["seat_skill_directive"],
llmwiki_knowledge_base_ids=extras["llmwiki_knowledge_base_ids"],
)
await agent_store.replace_skills(agent_id, next_skills)
await agent_store.set_extras(
agent_id,
tool_groups=extras["tool_groups"],
model=next_model,
)
if "soul" in fields:
await asyncio.to_thread(
agents_router._write_agent_soul,
agent_id,
payload.soul or "",
)
if {"name", "description"} & fields:
updated = await agent_store.update_any(
agent_id,
{"name": next_name, "description": next_description},
)
if updated is None:
raise HTTPException(status_code=404, detail=f"Agent '{agent_id}' not found")
record = updated
enabled = payload.enabled if "enabled" in fields and not bool(role["fixed"]) else None
sort_order = payload.sort_order if "sort_order" in fields and not bool(role["fixed"]) else None
if enabled is not None or sort_order is not None:
updated_role = await role_store.update_role(
agent_id,
enabled=enabled,
sort_order=sort_order,
)
if updated_role is None:
raise HTTPException(status_code=404, detail=f"Strategy agent '{agent_id}' not found")
role = updated_role
if not bool(role["fixed"]):
await asyncio.to_thread(_write_role_sidecar, agent_id, role)
except Exception:
await _rollback_strategy_update(
agent_id=agent_id,
agent_store=agent_store,
role_store=role_store,
record=original_record,
role=original_role,
extras=extras,
file_snapshot=file_snapshot,
)
raise
return await _to_item(role, record, include_config=True)
@router.delete("/{agent_id}", response_model=StrategyAgentItem)
async def disable_strategy_angle(agent_id: str, request: Request) -> StrategyAgentItem:
"""Soft-disable an angle while retaining its agent and historical links."""
await _require_admin(request)
agent_id = agents_router._validate_storage_id(agent_id)
async with _strategy_mutation_guard(agent_id):
return await _disable_strategy_angle_locked(agent_id, request)
async def _disable_strategy_angle_locked(
agent_id: str,
request: Request,
) -> StrategyAgentItem:
role, record = await _get_role_and_agent(request, agent_id)
if bool(role["fixed"]):
raise HTTPException(status_code=409, detail="Fixed strategy roles cannot be deleted")
if role.get("category") != "angle":
raise HTTPException(status_code=409, detail="Only strategy angle roles can be disabled")
updated = await get_strategy_agent_role_store(request).update_role(
agent_id,
enabled=False,
)
if updated is None:
raise HTTPException(status_code=404, detail=f"Strategy agent '{agent_id}' not found")
try:
await asyncio.to_thread(_write_role_sidecar, agent_id, updated)
except Exception:
await get_strategy_agent_role_store(request).update_role(
agent_id,
enabled=bool(role["enabled"]),
sort_order=int(role["sort_order"]),
)
raise
return await _to_item(updated, record, include_config=True)
__all__ = [
"StrategyAgentItem",
"StrategyAgentListResponse",
"StrategyAgentUpdateRequest",
"StrategyAngleCreateRequest",
"create_strategy_angle",
"disable_strategy_angle",
"ensure_strategy_agent_registry",
"list_strategy_agents",
"router",
"update_strategy_agent",
]
@@ -26,6 +26,7 @@ from deerflow.config.system_settings import (
PublishSquare,
PublishSquaresSettings,
SkillCompressionSettings,
StrategyProjectSettings,
get_module_tag_ids,
list_publish_squares,
load_system_settings,
@@ -60,6 +61,14 @@ class OrdinaryKnowledgeLanding(BaseModel):
mode: Literal["wiki", "weknora"] = "wiki"
class StrategyProjectSettingsResponse(BaseModel):
taiwan_strait_demo_enabled: bool = False
class StrategyProjectSettingsUpdateRequest(BaseModel):
taiwan_strait_demo_enabled: bool | None = None
@router.get("/ordinary-knowledge-landing", response_model=OrdinaryKnowledgeLanding)
async def get_ordinary_knowledge_landing() -> OrdinaryKnowledgeLanding:
return OrdinaryKnowledgeLanding(mode=load_system_settings().ordinary_knowledge_landing)
@@ -72,6 +81,35 @@ async def update_ordinary_knowledge_landing(body: OrdinaryKnowledgeLanding, requ
return OrdinaryKnowledgeLanding(mode=saved.ordinary_knowledge_landing)
def _strategy_project_settings_response(
settings: StrategyProjectSettings,
) -> StrategyProjectSettingsResponse:
return StrategyProjectSettingsResponse(
taiwan_strait_demo_enabled=settings.taiwan_strait_demo_enabled,
)
@router.get("/strategy-projects", response_model=StrategyProjectSettingsResponse)
async def get_strategy_project_settings() -> StrategyProjectSettingsResponse:
"""Return project-demo visibility. Any logged-in user may read it."""
return _strategy_project_settings_response(load_system_settings().strategy_projects)
@router.put("/strategy-projects", response_model=StrategyProjectSettingsResponse)
async def update_strategy_project_settings(
body: StrategyProjectSettingsUpdateRequest,
request: Request,
) -> StrategyProjectSettingsResponse:
"""Update project-demo visibility. Admin only."""
await _require_admin(request)
current = load_system_settings()
fields = body.model_dump(exclude_unset=True, exclude_none=True)
updated = current.strategy_projects.model_copy(update=fields)
saved = save_system_settings(current.model_copy(update={"strategy_projects": updated}))
return _strategy_project_settings_response(saved.strategy_projects)
class PromptPrefixUpdateRequest(BaseModel):
enabled: bool | None = None
switch_label: str | None = None