sync update from LAN repo (source master @ c21a2a4a)

This commit is contained in:
gozeros committed 2026-11-10 14:03:50 +08:00
1 parent ea9dcff9c0
commit 66a443e915
140 files changed
+13777 -1040

No files matched your search

@@ -264,17 +264,17 @@ def _get_enabled_skills():
def _get_enabled_skills_for_config(app_config: AppConfig | None = None) -> list[Skill]:
"""Return enabled skills using the caller's config source.
Resolve storage from the caller's config and reuse the parsed catalogue only
when its root matches. A cold cache or a different root falls back to that
storage, keeping request-scoped skill directories isolated.
Resolve storage from the caller's config and reuse the parsed catalogue only
when its root matches. A cold cache or a different root falls back to that
storage, keeping request-scoped skill directories isolated.
"""
if app_config is None:
return _get_enabled_skills()
storage = get_or_new_skill_storage(app_config=app_config)
warm = get_warm_enabled_skills(storage)
if warm is not None:
return warm
return _apply_always_on(_drop_archived_skills(list(storage.load_skills(enabled_only=True))))
storage = get_or_new_skill_storage(app_config=app_config)
warm = get_warm_enabled_skills(storage)
if warm is not None:
return warm
return _apply_always_on(_drop_archived_skills(list(storage.load_skills(enabled_only=True))))
def _skill_mutability_label(category: SkillCategory | str) -> str:
@@ -617,44 +617,44 @@ task(description="Oracle Cloud analysis", prompt="...", subagent_type="general-p
</subagent_system>"""
_ORDINARY_QA_HEADING_RULES = {
"hybrid_decimal": """- 一级章节使用 `## 一、标题`,二级章节使用 `### 1.1 标题`,三级章节使用 `#### 1.1.1 标题`。
- 二级章节按 `1.1`、`1.2`、`2.1` 的形式编号,三级及更深层级继续使用完整多级阿拉伯数字。
- 确需更深层级时,四级章节使用 `##### 1.1.1.1 标题`,五级章节使用 `###### 1.1.1.1.1 标题`。""",
"official_chinese": """- 一级章节使用 `## 一、标题`,二级章节使用 `### (一) 标题`,三级章节使用 `#### 1. 标题`。
- 确需更深层级时,四级章节使用 `##### (1) 标题`,五级章节使用 `###### 1) 标题`。""",
"decimal": """- 一级章节使用 `## 1 标题`,二级章节使用 `### 1.1 标题`,三级章节使用 `#### 1.1.1 标题`。
- 确需更深层级时,继续使用 `##### 1.1.1.1 标题`、`###### 1.1.1.1.1 标题`。""",
"chapter_section": """- 一级章节使用 `## 第一章 标题`,二级章节使用 `### 第一节 标题`,三级章节使用 `#### 一、标题`。
- 确需更深层级时,四级章节使用 `##### (一) 标题`,五级章节使用 `###### 1. 标题`。""",
"none": """- 各级章节只写标题文字,不手写编号:`## 一级标题`、`### 二级标题`、`#### 三级标题`。
- 确需更深层级时使用 `##### 四级标题`、`###### 五级标题`,仍不添加编号。""",
}
def _word_heading_numbering_style() -> str:
"""Return the configured Word heading-numbering preset with a safe default."""
try:
return load_system_settings().prompt_prefix.word_heading_numbering_style
except Exception:
logger.debug("Failed to read the Word heading-numbering style; using default", exc_info=True)
return "hybrid_decimal"
def _build_ordinary_qa_markdown_format_section() -> str:
rules = _ORDINARY_QA_HEADING_RULES.get(
_word_heading_numbering_style(),
_ORDINARY_QA_HEADING_RULES["hybrid_decimal"],
)
return f"""
<ordinary_qa_markdown_format>
当普通问答需要输出带章节结构的较长内容时,必须采用以下 Markdown 规范,以便下载为 Word 后得到正确的自动编号和公文标题格式:
- 文档主标题使用 `# 主标题`;主标题只写标题文字,不添加章节编号。
{rules}
- 默认禁止使用以 `-`、`*`、`+` 或 `•` 开头的无序圆点列表;并列内容优先改写为完整自然段,确需逐项表达时使用有序列表。只有用户明确要求无序列表时才使用。
- 简短问答不必为了套用格式而强行添加标题;本规范只约束实际使用的标题和列表。
</ordinary_qa_markdown_format>
"""
_ORDINARY_QA_HEADING_RULES = {
"hybrid_decimal": """- 一级章节使用 `## 一、标题`,二级章节使用 `### 1.1 标题`,三级章节使用 `#### 1.1.1 标题`。
- 二级章节按 `1.1`、`1.2`、`2.1` 的形式编号,三级及更深层级继续使用完整多级阿拉伯数字。
- 确需更深层级时,四级章节使用 `##### 1.1.1.1 标题`,五级章节使用 `###### 1.1.1.1.1 标题`。""",
"official_chinese": """- 一级章节使用 `## 一、标题`,二级章节使用 `### (一) 标题`,三级章节使用 `#### 1. 标题`。
- 确需更深层级时,四级章节使用 `##### (1) 标题`,五级章节使用 `###### 1) 标题`。""",
"decimal": """- 一级章节使用 `## 1 标题`,二级章节使用 `### 1.1 标题`,三级章节使用 `#### 1.1.1 标题`。
- 确需更深层级时,继续使用 `##### 1.1.1.1 标题`、`###### 1.1.1.1.1 标题`。""",
"chapter_section": """- 一级章节使用 `## 第一章 标题`,二级章节使用 `### 第一节 标题`,三级章节使用 `#### 一、标题`。
- 确需更深层级时,四级章节使用 `##### (一) 标题`,五级章节使用 `###### 1. 标题`。""",
"none": """- 各级章节只写标题文字,不手写编号:`## 一级标题`、`### 二级标题`、`#### 三级标题`。
- 确需更深层级时使用 `##### 四级标题`、`###### 五级标题`,仍不添加编号。""",
}
def _word_heading_numbering_style() -> str:
"""Return the configured Word heading-numbering preset with a safe default."""
try:
return load_system_settings().prompt_prefix.word_heading_numbering_style
except Exception:
logger.debug("Failed to read the Word heading-numbering style; using default", exc_info=True)
return "hybrid_decimal"
def _build_ordinary_qa_markdown_format_section() -> str:
rules = _ORDINARY_QA_HEADING_RULES.get(
_word_heading_numbering_style(),
_ORDINARY_QA_HEADING_RULES["hybrid_decimal"],
)
return f"""
<ordinary_qa_markdown_format>
当普通问答需要输出带章节结构的较长内容时,必须采用以下 Markdown 规范,以便下载为 Word 后得到正确的自动编号和公文标题格式:
- 文档主标题使用 `# 主标题`;主标题只写标题文字,不添加章节编号。
{rules}
- 默认禁止使用以 `-`、`*`、`+` 或 `•` 开头的无序圆点列表;并列内容优先改写为完整自然段,确需逐项表达时使用有序列表。只有用户明确要求无序列表时才使用。
- 简短问答不必为了套用格式而强行添加标题;本规范只约束实际使用的标题和列表。
</ordinary_qa_markdown_format>
"""
_ORDINARY_QA_VISUALIZATION_SECTION = """
@@ -1261,13 +1261,13 @@ RAG/reference display mode is enabled.
return prompt
def _get_memory_context(
agent_name: str | None = None,
*,
app_config: AppConfig | None = None,
injection_enabled: bool = True,
include_legacy_knowledge_routing: bool = True,
) -> str:
def _get_memory_context(
agent_name: str | None = None,
*,
app_config: AppConfig | None = None,
injection_enabled: bool = True,
include_legacy_knowledge_routing: bool = True,
) -> str:
"""组装注入系统提示词的记忆上下文 (Memory V2)。
通过 :class:`MemoryManager` 收集各 provider 的记忆块。P1 期只有 builtin
@@ -1278,10 +1278,10 @@ def _get_memory_context(
agent_name: agent 标识;``None`` 时按 "default" 处理。
app_config: 显式应用配置 (本函数实际按 per-user 覆盖解析生效配置)。
injection_enabled: 运行时开关;``False`` 时跳过注入直接返回空串。
include_legacy_knowledge_routing: 是否注入 ``/mnt/knowledge/routing.md``。
智能普通知识库检索已有数据库授权范围和专用检索工具时必须关闭,
避免旧文件路由把“这个库”错误引向沙箱目录;其它记忆 provider
仍按原配置保留。
include_legacy_knowledge_routing: 是否注入 ``/mnt/knowledge/routing.md``。
智能普通知识库检索已有数据库授权范围和专用检索工具时必须关闭,
避免旧文件路由把“这个库”错误引向沙箱目录;其它记忆 provider
仍按原配置保留。
Returns:
包在 ``<memory>`` 标签里的记忆上下文;未启用或为空时返回空串。
@@ -1306,11 +1306,11 @@ def _get_memory_context(
)
# 只取静态块 (builtin 的 frozen snapshot + Hindsight 的模式说明)。
# Hindsight 的动态召回需要当前 query,走 MemoryMiddleware.before_model。
context_content = manager.build_system_prompt(
excluded_provider_names=(
None if include_legacy_knowledge_routing else {"knowledge"}
)
)
context_content = manager.build_system_prompt(
excluded_provider_names=(
None if include_legacy_knowledge_routing else {"knowledge"}
)
)
if not context_content.strip():
return ""
@@ -1878,7 +1878,7 @@ def apply_prompt_template(
is_bootstrap: bool = False,
app_config: AppConfig | None = None,
memory_injection_enabled: bool = True,
include_legacy_knowledge_routing: bool = True,
include_legacy_knowledge_routing: bool = True,
rag_mode_enabled: bool = False,
is_notebook_mode: bool = False,
notebook_source_ids: list[int] | None = None,
@@ -1887,12 +1887,12 @@ def apply_prompt_template(
storage_agent_id = agent_id if agent_id is not None else agent_name
# Get memory context
memory_context = _get_memory_context(
storage_agent_id,
app_config=app_config,
injection_enabled=memory_injection_enabled,
include_legacy_knowledge_routing=include_legacy_knowledge_routing,
)
memory_context = _get_memory_context(
storage_agent_id,
app_config=app_config,
injection_enabled=memory_injection_enabled,
include_legacy_knowledge_routing=include_legacy_knowledge_routing,
)
# Include subagent section only if enabled (from runtime parameter)
n = max_concurrent_subagents
@@ -2004,8 +2004,8 @@ When a search, knowledge, skill, or MCP tool returns a result list:
if rag_mode_enabled
else ""
)
ordinary_qa_format_section = (
_build_ordinary_qa_markdown_format_section()
ordinary_qa_format_section = (
_build_ordinary_qa_markdown_format_section()
if _ordinary_qa_markdown_format_enabled()
and not is_bootstrap
and not writing_mode
@@ -136,13 +136,18 @@ def _build_runtime_middlewares(
# wrap_tool_call chain: its handler is the raw tool, so it observes the
# unconverted exception (before ToolErrorHandlingMiddleware turns it into
# an error ToolMessage) and the raw return value.
# Omit the recorder entirely while paused: no record allocation, skill-merge
# lookup, or fire-and-forget DB task is created by any tool invocation.
# Keep tool execution/error handling and LLM metrics independent of this flag.
if app_config.runtime_performance.tool_metrics_enabled:
from deerflow.agents.middlewares.tool_metrics_middleware import ToolMetricsMiddleware
middlewares.append(ToolMetricsMiddleware())
# Full auditing can stay paused under high concurrency while the low-volume
# skill-only recorder remains active. In skill-only mode non-skill calls are
# passed through without a merge query or fire-and-forget DB write.
performance = app_config.runtime_performance
if performance.tool_metrics_enabled or performance.skill_metrics_enabled:
from deerflow.agents.middlewares.tool_metrics_middleware import ToolMetricsMiddleware
middlewares.append(
ToolMetricsMiddleware(
skill_only=not performance.tool_metrics_enabled,
)
)
return middlewares
@@ -179,20 +184,20 @@ def build_subagent_runtime_middlewares(
model_name = app_config.models[0].name
model_config = app_config.get_model_config(model_name) if model_name else None
if model_config is not None and model_config.supports_vision:
from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware
middlewares.append(ViewImageMiddleware())
# Must remain the innermost model-call wrapper: subagent-specific context,
# vision payloads, system prompts and tool schemas all need to be included
# in the final input-size decision.
from deerflow.agents.middlewares.context_window_guard_middleware import ContextWindowGuardMiddleware
middlewares.append(
ContextWindowGuardMiddleware(
max_input_tokens=model_config.max_input_tokens if model_config is not None else None,
)
)
return middlewares
if model_config is not None and model_config.supports_vision:
from deerflow.agents.middlewares.view_image_middleware import ViewImageMiddleware
middlewares.append(ViewImageMiddleware())
# Must remain the innermost model-call wrapper: subagent-specific context,
# vision payloads, system prompts and tool schemas all need to be included
# in the final input-size decision.
from deerflow.agents.middlewares.context_window_guard_middleware import ContextWindowGuardMiddleware
middlewares.append(
ContextWindowGuardMiddleware(
max_input_tokens=model_config.max_input_tokens if model_config is not None else None,
)
)
return middlewares
@@ -1,6 +1,7 @@
"""Middleware that records per-tool-call metrics for the admin audit page.
Every tool / skill invocation ends with one row in ``tool_call_metrics``:
While the administrator-controlled call-metrics switch is enabled, every tool
/ skill invocation ends with one row in ``tool_call_metrics``:
- Successes record the wall-clock duration.
- Failures record a coarse ``error_category`` plus a one-line message.
@@ -40,6 +41,7 @@ from langgraph.errors import GraphBubbleUp
from langgraph.prebuilt.tool_node import ToolCallRequest
from langgraph.types import Command
from deerflow.config.system_settings import get_call_metrics_settings
from deerflow.persistence.engine import fire_and_forget_db_write, get_session_factory
from deerflow.persistence.tool_metrics import ToolMetricRecord, make_tool_metrics_store
from deerflow.persistence.tool_metrics.base import ToolMetricsStore
@@ -188,11 +190,18 @@ def _evaluate_result(result: Any, tool_name: str | None) -> tuple[str, str | Non
class ToolMetricsMiddleware(AgentMiddleware[AgentState]):
"""Wrap each tool call to time it and persist a metric row."""
"""Time tool calls, optionally persisting only attributable skill calls."""
def __init__(self, *, store: ToolMetricsStore | None = None, **kwargs: Any) -> None:
def __init__(
self,
*,
store: ToolMetricsStore | None = None,
skill_only: bool = False,
**kwargs: Any,
) -> None:
super().__init__(**kwargs)
self._store_override = store
self._skill_only = skill_only
# -- store / context ----------------------------------------------------
@@ -205,6 +214,12 @@ class ToolMetricsMiddleware(AgentMiddleware[AgentState]):
return None
return make_tool_metrics_store(sf)
@staticmethod
def _metrics_enabled() -> bool:
"""Read the administrator switch at call time so no restart is needed."""
return bool(get_call_metrics_settings().enabled)
@staticmethod
def _runtime_lookup(request: ToolCallRequest, keys: tuple[str, ...]) -> str | None:
runtime = getattr(request, "runtime", None)
@@ -280,7 +295,11 @@ class ToolMetricsMiddleware(AgentMiddleware[AgentState]):
handler: Callable[[ToolCallRequest], ToolMessage | Command],
) -> ToolMessage | Command:
record = self._build_base_record(request)
if is_internal_tool_name(record.tool_name):
if (
not self._metrics_enabled()
or is_internal_tool_name(record.tool_name)
or (self._skill_only and not record.skill_name)
):
return handler(request)
started = time.monotonic()
try:
@@ -303,7 +322,11 @@ class ToolMetricsMiddleware(AgentMiddleware[AgentState]):
handler: Callable[[ToolCallRequest], Awaitable[ToolMessage | Command]],
) -> ToolMessage | Command:
record = self._build_base_record(request)
if is_internal_tool_name(record.tool_name):
if (
not self._metrics_enabled()
or is_internal_tool_name(record.tool_name)
or (self._skill_only and not record.skill_name)
):
return await handler(request)
started = time.monotonic()
try:
@@ -482,13 +482,14 @@ def _load_and_cache_app_config(config_path: str | None = None) -> AppConfig:
)
performance = _app_config.runtime_performance
logger.info(
"RUNTIME_PERFORMANCE skill_view_reuse_enabled=%s skill_view_cache_enabled=%s model_timing_nonblocking_enabled=%s asyncio_thread_pool_enabled=%s asyncio_thread_pool_size=%d tool_metrics_enabled=%s",
"RUNTIME_PERFORMANCE skill_view_reuse_enabled=%s skill_view_cache_enabled=%s model_timing_nonblocking_enabled=%s asyncio_thread_pool_enabled=%s asyncio_thread_pool_size=%d tool_metrics_enabled=%s skill_metrics_enabled=%s",
performance.skill_view_reuse_enabled,
performance.skill_view_cache_enabled,
performance.model_timing_nonblocking_enabled,
performance.asyncio_thread_pool_enabled,
performance.asyncio_thread_pool_size,
performance.tool_metrics_enabled,
performance.skill_metrics_enabled,
)
return _app_config
@@ -2,9 +2,11 @@
Skill-view reuse and cache are on when those keys are absent. Set them to
false in config.yaml to restore a full refresh on every tool call. Model
timing and the Gateway thread pool stay off unless configured. If application
configuration cannot be loaded, every switch stays off. Tool-call metric writes
are paused by default; explicitly enable them to resume audit statistics.
timing and the Gateway thread pool stay off unless configured. Tool and skill
metrics are on by default so the management leaderboard has a complete source
of truth. Deployments that need to shed this best-effort audit write load can
explicitly pause either metric type in ``config.yaml``. If configuration
cannot be loaded, the fallback keeps every switch off.
"""
from pydantic import BaseModel, ConfigDict, Field
@@ -15,7 +17,14 @@ class RuntimePerformanceConfig(BaseModel):
skill_view_reuse_enabled: bool = Field(default=True, description="Reuse one verified skill view within each sandbox tool invocation. Set false to refresh on every call.")
skill_view_cache_enabled: bool = Field(default=True, description="Reuse unchanged skill views after validating source, target and availability versions. Set false to rebuild every call.")
tool_metrics_enabled: bool = Field(default=False, description="Persist tool/skill audit statistics to tool_call_metrics. Disabled by default to avoid competing with interactive database traffic; historical reads remain available.")
tool_metrics_enabled: bool = Field(
default=True,
description="Persist tool/skill audit statistics to tool_call_metrics. Enabled by default so management leaderboard tool rankings receive data; set false only to pause ordinary tool auditing.",
)
skill_metrics_enabled: bool = Field(
default=True,
description="Persist calls that can be attributed to a concrete skill, keeping skill statistics available even if ordinary tool auditing is paused.",
)
model_timing_nonblocking_enabled: bool = Field(default=False, description="Dispatch model timing logs through a dedicated bounded queue, outside the shared tool executor")
asyncio_thread_pool_enabled: bool = Field(default=False, description="Override the Gateway event loop's default executor at startup; disabled preserves Python defaults")
asyncio_thread_pool_size: int = Field(default=100, ge=1, le=1024, strict=True, description="Maximum Gateway executor threads when enabled, unless overridden by the documented environment variables")
@@ -24,7 +33,12 @@ class RuntimePerformanceConfig(BaseModel):
# Field defaults turn the skill-view fast path on. This fallback is only for
# callers that cannot read application configuration, and it keeps every
# switch off.
_DEFAULT = RuntimePerformanceConfig(skill_view_reuse_enabled=False, skill_view_cache_enabled=False)
_DEFAULT = RuntimePerformanceConfig(
skill_view_reuse_enabled=False,
skill_view_cache_enabled=False,
tool_metrics_enabled=False,
skill_metrics_enabled=False,
)
def get_runtime_performance_config() -> RuntimePerformanceConfig:
@@ -21,7 +21,7 @@ from pathlib import Path
from typing import Literal
from uuid import uuid4
from pydantic import BaseModel, ConfigDict, Field, field_validator
from pydantic import BaseModel, ConfigDict, Field, field_validator, model_validator
from deerflow.config.llmwiki_config import LlmWikiRuntimeOverride
from deerflow.config.runtime_paths import runtime_home
@@ -474,6 +474,20 @@ class SkillCompressionSettings(BaseModel):
model_config = ConfigDict(extra="ignore")
class SkillVersioningSettings(BaseModel):
"""Deployment-wide gate for custom-skill package version history.
The default is intentionally disabled so existing deployments retain the
legacy in-place editing behaviour until an administrator opts in.
"""
enabled: bool = Field(
default=False,
description="Whether custom-skill package versioning and switching are enabled",
)
model_config = ConfigDict(extra="ignore")
class AgentModuleSettings(BaseModel):
"""Admin-configured「按类型聚合」module → selected agent-tag ids.
@@ -668,6 +682,24 @@ class WriteFileCompatibilitySettings(BaseModel):
model_config = ConfigDict(extra="ignore")
class CallMetricsSettings(BaseModel):
"""Administrator-controlled recording for tool and skill call statistics.
Both rankings use the same ``tool_call_metrics`` audit stream. Keeping a
single switch prevents a partially enabled configuration where the
management page can show one ranking but not the other.
"""
enabled: bool = Field(
default=True,
description=(
"Whether new tool and skill calls are persisted for management "
"statistics. Existing records are retained when disabled."
),
)
model_config = ConfigDict(extra="ignore")
class RetryKeepPartialSettings(BaseModel):
"""Keep already-streamed partial answers visible across silent LLM retries.
@@ -717,6 +749,15 @@ class RoundtableRoomLimitSettings(BaseModel):
"but never extend this deadline."
),
)
lease_minutes: int = Field(
default=5,
ge=1,
le=60,
description=(
"How long a foreground step-2 lease stays occupied without a renewal. "
"The browser heartbeat renews it; this does not extend max_hold_minutes."
),
)
max_cycles: int = Field(
default=8,
ge=2,
@@ -769,7 +810,40 @@ class HtmlMapSettings(BaseModel):
model_config = ConfigDict(extra="ignore")
_GENERATED_PAGE_LOGO_FILE_RE = re.compile(r"^logo-[a-f0-9]{32}\.(?:png|jpg|webp)$")
class GeneratedPageBrandingSettings(BaseModel):
"""Optional generated-page logo settings retained for offline bundles."""
chrome_enabled: bool = True
header_layout: Literal["left", "center"] = "center"
system_name: str | None = Field(default=None, max_length=80)
footer_text: str | None = Field(default=None, max_length=160)
logo_filename: str | None = None
logo_mode: Literal["custom", "default", "none"] = "custom"
logo_media_type: Literal["image/png", "image/jpeg", "image/webp"] | None = None
logo_version: str | None = Field(default=None, max_length=64)
model_config = ConfigDict(extra="ignore")
@field_validator("logo_filename")
@classmethod
def _validate_logo_filename(cls, value: str | None) -> str | None:
if value is None:
return None
normalized = str(value).strip().lower()
if not _GENERATED_PAGE_LOGO_FILE_RE.fullmatch(normalized):
raise ValueError("Invalid generated-page logo filename")
return normalized
_APP_IDENTITY_LOGO_FILE_RE = re.compile(r"^logo-[a-f0-9]{32}\.(?:png|jpg|webp)$")
_APP_IDENTITY_LIGHT_RED_HEADER_FILE_RE = re.compile(
r"^light-red-header-[a-f0-9]{32}\.(?:png|jpg|webp|svg)$"
)
_APP_IDENTITY_LIGHT_RED_ACTIVE_FILE_RE = re.compile(
r"^light-red-active-[a-f0-9]{32}\.(?:png|jpg|webp|svg)$"
)
class AppIdentitySettings(BaseModel):
@@ -780,9 +854,21 @@ class AppIdentitySettings(BaseModel):
"""
system_name: str = Field(default="", max_length=80)
header_title_font_mode: Literal["adaptive", "fixed"] = "adaptive"
header_title_font_size: int = Field(default=30, ge=16, le=40)
logo_filename: str | None = None
logo_media_type: Literal["image/png", "image/jpeg", "image/webp"] | None = None
logo_version: str | None = None
light_red_header_background_filename: str | None = None
light_red_header_background_media_type: Literal[
"image/png", "image/jpeg", "image/webp", "image/svg+xml"
] | None = None
light_red_header_background_version: str | None = None
light_red_nav_active_filename: str | None = None
light_red_nav_active_media_type: Literal[
"image/png", "image/jpeg", "image/webp", "image/svg+xml"
] | None = None
light_red_nav_active_version: str | None = None
model_config = ConfigDict(extra="ignore")
@field_validator("system_name")
@@ -801,6 +887,26 @@ class AppIdentitySettings(BaseModel):
raise ValueError("Invalid application logo filename")
return normalized
@field_validator("light_red_header_background_filename")
@classmethod
def _validate_light_red_header_filename(cls, value: str | None) -> str | None:
if value is None:
return None
normalized = str(value).strip().lower()
if not _APP_IDENTITY_LIGHT_RED_HEADER_FILE_RE.fullmatch(normalized):
raise ValueError("Invalid light-red header background filename")
return normalized
@field_validator("light_red_nav_active_filename")
@classmethod
def _validate_light_red_active_filename(cls, value: str | None) -> str | None:
if value is None:
return None
normalized = str(value).strip().lower()
if not _APP_IDENTITY_LIGHT_RED_ACTIVE_FILE_RE.fullmatch(normalized):
raise ValueError("Invalid light-red active navigation filename")
return normalized
def app_identity_logo_path(
settings: AppIdentitySettings | None = None,
@@ -814,6 +920,42 @@ def app_identity_logo_path(
return path if path.is_file() else None
def app_identity_light_red_header_background_path(
settings: AppIdentitySettings | None = None,
) -> Path | None:
"""Resolve the uploaded light-red header background inside runtime storage."""
current = settings or load_system_settings().app_identity
if not current.light_red_header_background_filename:
return None
path = runtime_home() / "app-identity" / current.light_red_header_background_filename
return path if path.is_file() else None
def app_identity_light_red_nav_active_path(
settings: AppIdentitySettings | None = None,
) -> Path | None:
"""Resolve the uploaded light-red active-navigation image inside runtime storage."""
current = settings or load_system_settings().app_identity
if not current.light_red_nav_active_filename:
return None
path = runtime_home() / "app-identity" / current.light_red_nav_active_filename
return path if path.is_file() else None
def generated_page_logo_path(
settings: GeneratedPageBrandingSettings | None = None,
) -> Path | None:
"""Resolve the custom generated-page logo without accepting arbitrary paths."""
current = settings or load_system_settings().generated_page_branding
if current.logo_mode != "custom" or not current.logo_filename:
return None
path = runtime_home() / "generated-page-branding" / current.logo_filename
return path if path.is_file() else None
class HtmlRuntimeSettings(BaseModel):
"""Addresses written into newly generated HTML pages.
@@ -844,6 +986,108 @@ class StrategyProjectSettings(BaseModel):
model_config = ConfigDict(extra="ignore")
class GeneralQaPageDescription(BaseModel):
"""Administrator-provided copy for the ordinary Q&A landing page."""
welcome_title: str = Field(default="", max_length=80)
welcome_description: str = Field(default="", max_length=500)
input_placeholder: str = Field(default="", max_length=120)
model_config = ConfigDict(extra="ignore")
@field_validator("welcome_title", "welcome_description", "input_placeholder")
@classmethod
def _normalize_copy(cls, value: str | None) -> str:
return str(value or "").strip()
class GeneralQaPageDescriptions(BaseModel):
"""Separate ordinary-Q&A copy for the full and compact layouts."""
full: GeneralQaPageDescription = Field(default_factory=GeneralQaPageDescription)
compact: GeneralQaPageDescription = Field(default_factory=GeneralQaPageDescription)
model_config = ConfigDict(extra="ignore")
@model_validator(mode="before")
@classmethod
def _migrate_legacy_single_description(cls, value: object) -> object:
if isinstance(value, GeneralQaPageDescription):
return {"full": value, "compact": value}
if not isinstance(value, dict):
return value
if "full" in value or "compact" in value:
return value
legacy = {
key: value.get(key, "")
for key in ("welcome_title", "welcome_description", "input_placeholder")
}
return {"full": legacy, "compact": legacy}
class PageHeaderDescription(BaseModel):
"""Configurable title and explanatory copy for a product landing page."""
title: str = Field(default="", max_length=80)
description: str = Field(default="", max_length=500)
model_config = ConfigDict(extra="ignore")
@field_validator("title", "description")
@classmethod
def _normalize_copy(cls, value: str | None) -> str:
return str(value or "").strip()
class AIWritingGuideCard(BaseModel):
"""Editable text for one of the fixed AI-writing welcome cards."""
title: str = Field(default="", max_length=80)
description: str = Field(default="", max_length=240)
model_config = ConfigDict(extra="ignore")
@field_validator("title", "description")
@classmethod
def _normalize_copy(cls, value: str | None) -> str:
return str(value or "").strip()
def _empty_ai_writing_guide_cards() -> list[AIWritingGuideCard]:
return [AIWritingGuideCard() for _ in range(3)]
class AIWritingPageDescription(PageHeaderDescription):
"""Configurable copy for the classic AI-writing welcome page."""
guide_cards: list[AIWritingGuideCard] = Field(
default_factory=_empty_ai_writing_guide_cards,
max_length=3,
)
@model_validator(mode="before")
@classmethod
def _keep_three_guide_cards(cls, value: object) -> object:
if not isinstance(value, dict) or not isinstance(value.get("guide_cards"), list):
return value
cards = value["guide_cards"][:3]
return {**value, "guide_cards": [*cards, *({} for _ in range(3 - len(cards)))]}
class PageDescriptionsSettings(BaseModel):
"""Page-scoped, administrator-managed display copy."""
general_qa: GeneralQaPageDescriptions = Field(default_factory=GeneralQaPageDescriptions)
knowledge_base: PageHeaderDescription = Field(default_factory=PageHeaderDescription)
ai_writing: AIWritingPageDescription = Field(default_factory=AIWritingPageDescription)
strategy_projects: PageHeaderDescription = Field(default_factory=PageHeaderDescription)
deep_research: PageHeaderDescription = Field(default_factory=PageHeaderDescription)
gongwen: PageHeaderDescription = Field(default_factory=PageHeaderDescription)
light_app_management: PageHeaderDescription = Field(default_factory=PageHeaderDescription)
light_app_list: PageHeaderDescription = Field(default_factory=PageHeaderDescription)
agents: PageHeaderDescription = Field(default_factory=PageHeaderDescription)
business_chains: PageHeaderDescription = Field(default_factory=PageHeaderDescription)
skills: PageHeaderDescription = Field(default_factory=PageHeaderDescription)
knowledge_management: PageHeaderDescription = Field(default_factory=PageHeaderDescription)
model_config = ConfigDict(extra="ignore")
class ModelPromptSuffix(BaseModel):
"""Administrator-owned instructions appended to one configured model's system prompt."""
@@ -862,9 +1106,14 @@ class SystemSettings(BaseModel):
private_square: PrivateSquareSettings = Field(default_factory=PrivateSquareSettings)
publish_squares: PublishSquaresSettings = Field(default_factory=PublishSquaresSettings)
appearance: AppearanceSettings = Field(default_factory=AppearanceSettings)
generated_page_branding: GeneratedPageBrandingSettings = Field(
default_factory=GeneratedPageBrandingSettings
)
page_descriptions: PageDescriptionsSettings = Field(default_factory=PageDescriptionsSettings)
citation_display: CitationDisplaySettings = Field(default_factory=CitationDisplaySettings)
leaderboard: LeaderboardSettings = Field(default_factory=LeaderboardSettings)
skill_compression: SkillCompressionSettings = Field(default_factory=SkillCompressionSettings)
skill_versioning: SkillVersioningSettings = Field(default_factory=SkillVersioningSettings)
plugin_management: PluginManagementSettings = Field(default_factory=PluginManagementSettings)
agent_modules: AgentModuleSettings = Field(default_factory=AgentModuleSettings)
wx_common_agents: WxCommonAgentsSettings = Field(default_factory=WxCommonAgentsSettings)
@@ -875,6 +1124,7 @@ class SystemSettings(BaseModel):
write_file_compatibility: WriteFileCompatibilitySettings = Field(
default_factory=WriteFileCompatibilitySettings
)
call_metrics: CallMetricsSettings = Field(default_factory=CallMetricsSettings)
retry_keep_partial: RetryKeepPartialSettings = Field(
default_factory=RetryKeepPartialSettings
)
@@ -1007,6 +1257,19 @@ def get_write_file_compatibility_settings() -> WriteFileCompatibilitySettings:
return WriteFileCompatibilitySettings()
def get_call_metrics_settings() -> CallMetricsSettings:
"""Return the live call-metrics switch, defaulting to recording enabled."""
try:
return load_system_settings().call_metrics
except Exception:
logger.debug(
"Failed to read call metrics setting; keeping metrics enabled",
exc_info=True,
)
return CallMetricsSettings()
def get_roundtable_room_limit_settings() -> RoundtableRoomLimitSettings:
"""Return the admin-controlled roundtable room cap, defaulting to 3 enabled rooms."""
try:
@@ -0,0 +1,321 @@
"""Build portable ZIP bundles for generated HTML artifacts.
Generated pages intentionally reference the Gateway's vendored browser runtime
instead of public CDNs. A plain ``.html`` download therefore stops working
after it is moved away from the DeerFlow deployment. This module rewrites
those trusted Gateway URLs to relative paths and copies the corresponding
packaged assets into a ZIP. It never downloads arbitrary third-party URLs.
"""
from __future__ import annotations
import hashlib
import json
import re
import zipfile
from dataclasses import dataclass
from importlib.resources import files
from pathlib import Path, PurePosixPath
from deerflow.html_runtime.public_images import resolve_html_image_path, verify_html_image_token
_STATIC_ASSETS = {
"alpine.min.js",
"bootstrap.bundle.min.js",
"bootstrap.min.css",
"brand-logo-dark.png",
"echarts.min.js",
"g6.min.js",
"leaflet.css",
"leaflet.js",
"topbar-dark.svg",
"topbar-light.svg",
}
_GEO_MAP_ASSETS = {
"china-provinces.geojson",
"japan-prefectures.geojson",
"taiwan-counties.geojson",
"us-states.geojson",
}
_COGNITIVE_ASSET_SUFFIXES = {
".css",
".js",
".json",
".jpeg",
".jpg",
".mjs",
".png",
".svg",
".woff2",
}
_LICENSE_BY_ASSET = {
"alpine.min.js": "LICENSE.alpine.txt",
"bootstrap.bundle.min.js": "LICENSE.bootstrap.txt",
"bootstrap.min.css": "LICENSE.bootstrap.txt",
"echarts.min.js": "LICENSE.echarts.txt",
"g6.min.js": "LICENSE.g6.txt",
"leaflet.css": "LICENSE.leaflet.txt",
"leaflet.js": "LICENSE.leaflet.txt",
}
_RUNTIME_ARCHIVE_ROOT = PurePosixPath("assets/html-runtime")
_HTML_IMAGES_ARCHIVE_ROOT = PurePosixPath("assets/html-images")
_STANDARD_RUNTIME_BASE_RE = (
r"(?:https?://[^/\"'\s<>()]+)?"
r"(?:/[A-Za-z0-9._~!$&()*+,;=:@%+-]+)*/api/public/html-runtime"
)
_HTML_IMAGE_URL_RE = re.compile(
r"(?P<url>(?:https?://[^/\"'\s<>()]+)?"
r"(?:/[A-Za-z0-9._~!$&()*+,;=:@%+-]+)*/api/public/html-images/"
r"(?P<token>[^\"'\s<>()?#]+)(?:\?[^\"'\s<>()#]*)?)",
re.IGNORECASE,
)
_EXTERNAL_URL_RE = re.compile(r"https?://[^\s\"'<>]+", re.IGNORECASE)
@dataclass(frozen=True)
class OfflineBundleResult:
"""Summary of one completed offline bundle."""
bundled_assets: tuple[str, ...]
external_urls: tuple[str, ...]
def _runtime_base_pattern(runtime_base_url: str) -> str:
bases = [_STANDARD_RUNTIME_BASE_RE]
configured = str(runtime_base_url or "").strip().rstrip("/")
if configured:
bases.insert(0, re.escape(configured))
return "(?:" + "|".join(bases) + ")"
def _safe_runtime_source(runtime_dir: Path, relative_path: str) -> Path | None:
"""Resolve only assets that the public HTML-runtime router exposes."""
normalized = relative_path.strip().lstrip("/").replace("\\", "/")
pure_path = PurePosixPath(normalized)
if not normalized or pure_path.is_absolute() or ".." in pure_path.parts:
return None
allowed = False
if len(pure_path.parts) == 1 and normalized in _STATIC_ASSETS:
allowed = True
elif len(pure_path.parts) == 2 and pure_path.parts[0] == "maps" and pure_path.name in _GEO_MAP_ASSETS:
allowed = True
elif pure_path.parts and pure_path.parts[0] == "cognitive-situation-map":
allowed = pure_path.suffix.lower() in _COGNITIVE_ASSET_SUFFIXES
if not allowed:
return None
root = runtime_dir.resolve()
source = (root / Path(*pure_path.parts)).resolve()
try:
source.relative_to(root)
except ValueError:
return None
return source if source.is_file() else None
def _add_file(
archive_files: dict[str, Path],
archive_path: PurePosixPath,
source: Path,
) -> None:
archive_files[archive_path.as_posix()] = source
def _add_cognitive_runtime(archive_files: dict[str, Path], runtime_dir: Path) -> None:
source_root = runtime_dir / "cognitive-situation-map"
if not source_root.is_dir():
return
for source in source_root.rglob("*"):
if not source.is_file():
continue
is_license = source.name.lower().startswith("license")
if source.suffix.lower() not in _COGNITIVE_ASSET_SUFFIXES and not is_license:
continue
relative = source.relative_to(runtime_dir)
_add_file(archive_files, _RUNTIME_ARCHIVE_ROOT / PurePosixPath(relative.as_posix()), source)
def _generated_logo_destination(generated_logo_path: Path | None) -> PurePosixPath:
suffix = generated_logo_path.suffix.lower() if generated_logo_path is not None else ".png"
if suffix not in {".jpg", ".jpeg", ".png", ".webp"}:
suffix = ".png"
return _RUNTIME_ARCHIVE_ROOT / f"generated-page-logo{suffix}"
def _runtime_script(
runtime_dir: Path,
*,
map_tile_url: str,
include_geo_maps: bool,
) -> str:
config: dict[str, object] = {"geoMaps": {}, "mapTileUrl": map_tile_url}
if include_geo_maps:
config["geoMaps"] = {
Path(filename).stem: (_RUNTIME_ARCHIVE_ROOT / "maps" / filename).as_posix()
for filename in sorted(_GEO_MAP_ASSETS)
}
prefix = "window.DEERFLOW_HTML_RUNTIME_CONFIG=" + json.dumps(
config,
ensure_ascii=False,
separators=(",", ":"),
) + ";\n"
return prefix + (runtime_dir / "deerflow-runtime.js").read_text(encoding="utf-8")
def _readme(original_name: str, external_urls: list[str]) -> str:
external_note = (
"未打包的外部地址已记录在 manifest.json 的 external_urls 中;例如在线地图瓦片、"
"用户主动引用的第三方图片或接口仍需要网络。"
if external_urls
else "本页没有检测到仍需联网的 http(s) 地址。"
)
return (
"DeerFlow 网页离线包\n"
"====================\n\n"
f"原始文件:{original_name}\n"
"入口文件:index.html\n"
"依赖目录:assets/\n\n"
"部署方式:请保持目录结构不变,将解压后的全部文件一起放到任意静态网站目录。\n"
"若页面含 GeoJSON 地图等 fetch 请求,不建议直接双击 file:// 打开;可使用 Nginx、"
"Apache、IIS 或其他静态 HTTP 服务访问 index.html。\n\n"
f"{external_note}\n"
)
def build_html_offline_bundle(
html_path: Path,
destination: Path,
*,
runtime_base_url: str,
map_tile_url: str,
generated_logo_path: Path | None = None,
runtime_dir: Path | None = None,
) -> OfflineBundleResult:
"""Write a portable HTML ZIP to *destination* and return its manifest summary."""
html_path = Path(html_path)
destination = Path(destination)
runtime_dir = runtime_dir or Path(str(files("deerflow.html_runtime.assets")))
runtime_dir = Path(runtime_dir)
html = html_path.read_text(encoding="utf-8", errors="replace")
archive_files: dict[str, Path] = {}
generated_files: dict[str, str] = {}
bundled_assets: set[str] = set()
licenses: set[str] = set()
include_geo_maps = bool(re.search(r"data-df-geo\s*=", html, re.IGNORECASE))
uses_leaflet_map = bool(re.search(r"data-df-map\s*=", html, re.IGNORECASE))
base_pattern = _runtime_base_pattern(runtime_base_url)
cognitive_base_re = re.compile(
rf"(?P<url>{base_pattern}/cognitive-situation-map)(?=$|[\"'\s<>()/])",
re.IGNORECASE,
)
def replace_cognitive_base(match: re.Match[str]) -> str:
_add_cognitive_runtime(archive_files, runtime_dir)
bundled_assets.add((_RUNTIME_ARCHIVE_ROOT / "cognitive-situation-map").as_posix() + "/")
return (_RUNTIME_ARCHIVE_ROOT / "cognitive-situation-map").as_posix()
html = cognitive_base_re.sub(replace_cognitive_base, html)
runtime_url_re = re.compile(
rf"(?P<url>{base_pattern}/(?P<asset>[A-Za-z0-9._/-]+)"
r"(?:\?[^\"'\s<>()#]*)?)",
re.IGNORECASE,
)
def replace_runtime_url(match: re.Match[str]) -> str:
asset = match.group("asset").strip("/")
if asset == "generated-page-logo":
source = generated_logo_path if generated_logo_path and generated_logo_path.is_file() else runtime_dir / "brand-logo-dark.png"
if not source.is_file():
return match.group("url")
archive_path = _generated_logo_destination(source)
_add_file(archive_files, archive_path, source)
bundled_assets.add(archive_path.as_posix())
return archive_path.as_posix()
if asset == "deerflow-runtime.js":
source = runtime_dir / asset
if not source.is_file():
return match.group("url")
archive_path = _RUNTIME_ARCHIVE_ROOT / asset
generated_files[archive_path.as_posix()] = _runtime_script(
runtime_dir,
map_tile_url=map_tile_url,
include_geo_maps=include_geo_maps,
)
bundled_assets.add(archive_path.as_posix())
if include_geo_maps:
for filename in sorted(_GEO_MAP_ASSETS):
map_source = _safe_runtime_source(runtime_dir, f"maps/{filename}")
if map_source is not None:
map_archive_path = _RUNTIME_ARCHIVE_ROOT / "maps" / filename
_add_file(archive_files, map_archive_path, map_source)
bundled_assets.add(map_archive_path.as_posix())
return archive_path.as_posix()
source = _safe_runtime_source(runtime_dir, asset)
if source is None:
return match.group("url")
archive_path = _RUNTIME_ARCHIVE_ROOT / PurePosixPath(asset)
_add_file(archive_files, archive_path, source)
bundled_assets.add(archive_path.as_posix())
license_name = _LICENSE_BY_ASSET.get(asset)
if license_name and (runtime_dir / license_name).is_file():
licenses.add(license_name)
return archive_path.as_posix()
html = runtime_url_re.sub(replace_runtime_url, html)
def replace_html_image(match: re.Match[str]) -> str:
token = match.group("token")
try:
_thread_id, _kind, filename = verify_html_image_token(token)
source = resolve_html_image_path(_thread_id, _kind, filename)
except (FileNotFoundError, ValueError):
return match.group("url")
digest = hashlib.sha256(token.encode("utf-8")).hexdigest()[:12]
safe_name = Path(filename).name
archive_path = _HTML_IMAGES_ARCHIVE_ROOT / f"{digest}-{safe_name}"
_add_file(archive_files, archive_path, source)
bundled_assets.add(archive_path.as_posix())
return archive_path.as_posix()
html = _HTML_IMAGE_URL_RE.sub(replace_html_image, html)
external_url_set = {
match.group(0).rstrip("),.;")
for match in _EXTERNAL_URL_RE.finditer(html)
}
if uses_leaflet_map and str(map_tile_url).lower().startswith(("http://", "https://")):
external_url_set.add(str(map_tile_url))
external_urls = sorted(external_url_set)
manifest = {
"format": "deerflow-html-offline-bundle-v1",
"entry": "index.html",
"source_name": html_path.name,
"bundled_assets": sorted(bundled_assets),
"external_urls": external_urls,
}
destination.parent.mkdir(parents=True, exist_ok=True)
with zipfile.ZipFile(destination, "w", compression=zipfile.ZIP_DEFLATED, compresslevel=6) as archive:
archive.writestr("index.html", html.encode("utf-8"))
archive.writestr(
"manifest.json",
json.dumps(manifest, ensure_ascii=False, indent=2).encode("utf-8"),
)
archive.writestr("README.txt", _readme(html_path.name, external_urls).encode("utf-8"))
for archive_path, source in sorted(archive_files.items()):
archive.write(source, archive_path)
for archive_path, content in sorted(generated_files.items()):
archive.writestr(archive_path, content.encode("utf-8"))
for license_name in sorted(licenses):
archive.write(runtime_dir / license_name, f"THIRD_PARTY_LICENSES/{license_name}")
return OfflineBundleResult(
bundled_assets=tuple(sorted(bundled_assets)),
external_urls=tuple(external_urls),
)
@@ -36,7 +36,9 @@ from deerflow.persistence.roundtable_jobs.model import RoundtableJobRow
from deerflow.persistence.roundtable_jobs.sql import compute_active_dedupe_key
from deerflow.persistence.roundtable_rooms.model import RoundtableRoomLeaseRow
LEASE_SECONDS = 60
DEFAULT_LEASE_SECONDS = 5 * 60
MIN_LEASE_SECONDS = 60
MAX_LEASE_SECONDS = 60 * 60
JOB_LIVE_SECONDS = 15 * 60
OCCUPYING_JOB_STATUSES = ("queued", "running", "awaiting_input", "cancel_requested")
# A background job keeps running while Step 3 generates its artifacts, but the
@@ -80,6 +82,15 @@ def _job_is_live(
return updated is not None and updated >= live_after
def normalize_lease_seconds(value: int | None) -> int:
"""Clamp a foreground room lease to the supported 1–60 minute window."""
try:
seconds = int(value) if value is not None else DEFAULT_LEASE_SECONDS
except (TypeError, ValueError):
seconds = DEFAULT_LEASE_SECONDS
return max(MIN_LEASE_SECONDS, min(MAX_LEASE_SECONDS, seconds))
def _hard_deadline_reached(
created_at: datetime | None,
now: datetime,
@@ -104,6 +115,7 @@ class RoundtableRoomRepository:
enabled: bool,
max_rooms: int,
max_hold_minutes: int = 30,
lease_seconds: int = DEFAULT_LEASE_SECONDS,
extra_keys: set[str] | Mapping[str, str | None] | None = None,
) -> dict[str, Any]:
"""Atomically reserve/renew a room, or reject when the pool is full."""
@@ -119,6 +131,7 @@ class RoundtableRoomRepository:
enabled=enabled,
max_rooms=max_rooms,
max_hold_minutes=max_hold_minutes,
lease_seconds=lease_seconds,
extra_keys=extra_keys,
)
@@ -133,6 +146,7 @@ class RoundtableRoomRepository:
enabled: bool,
max_rooms: int,
max_hold_minutes: int = 30,
lease_seconds: int = DEFAULT_LEASE_SECONDS,
extra_keys: set[str] | Mapping[str, str | None] | None = None,
) -> dict[str, Any]:
"""Atomically admit a pre-resolved room key.
@@ -201,6 +215,7 @@ class RoundtableRoomRepository:
task_id=task_id,
holder_user_id=holder_user_id,
now=now,
lease_seconds=lease_seconds,
)
await session.commit()
return self._decision(
@@ -272,6 +287,7 @@ class RoundtableRoomRepository:
enabled: bool,
max_rooms: int,
max_hold_minutes: int = 30,
lease_seconds: int = DEFAULT_LEASE_SECONDS,
extra_keys: set[str] | Mapping[str, str | None] | None = None,
) -> dict[str, Any]:
"""Renew one live foreground lease without ever creating it.
@@ -298,6 +314,7 @@ class RoundtableRoomRepository:
enabled=enabled,
max_rooms=max_rooms,
max_hold_minutes=max_hold_minutes,
lease_seconds=lease_seconds,
extra_keys=extra_keys,
)
@@ -309,6 +326,7 @@ class RoundtableRoomRepository:
enabled: bool,
max_rooms: int,
max_hold_minutes: int = 30,
lease_seconds: int = DEFAULT_LEASE_SECONDS,
extra_keys: set[str] | Mapping[str, str | None] | None = None,
) -> dict[str, Any]:
"""Renew a resolved persisted key without creating a missing lease."""
@@ -354,7 +372,7 @@ class RoundtableRoomRepository:
message="会商连接已断开,请重新恢复研讨。" if enabled else "",
)
row.lease_until = now + timedelta(seconds=LEASE_SECONDS)
row.lease_until = now + timedelta(seconds=normalize_lease_seconds(lease_seconds))
row.updated_at = now
await session.commit()
return self._decision(
@@ -538,9 +556,10 @@ class RoundtableRoomRepository:
task_id: str | None,
holder_user_id: str | None,
now: datetime,
lease_seconds: int = DEFAULT_LEASE_SECONDS,
) -> None:
row = await session.get(RoundtableRoomLeaseRow, room_key)
lease_until = now + timedelta(seconds=LEASE_SECONDS)
lease_until = now + timedelta(seconds=normalize_lease_seconds(lease_seconds))
if row is None:
session.add(
RoundtableRoomLeaseRow(
@@ -23,7 +23,7 @@ from deerflow.config.agents_config import AGENT_ID_PATTERN, load_agent_config, l
from deerflow.config.paths import get_paths
from deerflow.persistence.scheduled_tasks import ScheduledTaskStore
from deerflow.runtime.scheduler import html_page as html_page_utils
from deerflow.runtime.scheduler import template_fill
from deerflow.runtime.scheduler import template_fill, template_store
from deerflow.runtime.scheduler.element import ElementDeliveryClient
from deerflow.runtime.serialization import serialize_channel_values
from deerflow.runtime.user_context import reset_current_user, set_current_user
@@ -1636,6 +1636,10 @@ class ScheduledTaskService:
# 不影响 Markdown 生成等其它正常操作。缺省(未存该键的老任务)视为开启:
# 模板有真实数据来源后,默认走「智能体检索 → 转换填充」,显式 False 才关闭。
extract = cfg.get("template_extract") is not False
# 「抽取信息写回模板数据」:开启后转换成功的抽取结果除填充本次产物外,还会
# 写回模板的 data.json(默认数据持久化——管理页预览与后续任务即时沿用新数据)。
# 只写数据,MANIFEST(系统名称/导航页面等)绝不动;缺省(老任务)视为关闭。
writeback = cfg.get("template_data_writeback") is True
also_markdown = _task_requires_markdown(task)
prompt = str(task.get("prompt") or "").strip()
description = str(task.get("description") or "").strip()
@@ -1702,8 +1706,21 @@ class ScheduledTaskService:
page_title, page_subtitle = template_fill.pop_page_titles(converted)
# 子页面没抽到有效内容的,回退模板原有数据,避免子页面空白。
data_obj = template_fill.merge_with_reference(tpl_id, converted)
# 字段管理里「接受抽取更新」被关闭(锁定)的字段,恢复模板现有值,
# 抽取结果不覆盖——对本次产物与(开启时的)数据写回同时生效。
data_obj = template_store.restore_locked_fields(tpl_id, data_obj)
content = f"已检索数据并套用模板「{spec.name}」(空子页面回退原数据,含全部子页面)"
used_default = False
if writeback:
try:
# 抽取结果写回模板默认数据(data.json)——仅数据,MANIFEST/系统
# 名称不动;管理页预览与后续任务即时基于更新后的默认数据。
template_store.write_template_data(tpl_id, data_obj)
content += ";抽取数据已写回模板默认数据"
except Exception:
logger.warning(
"模板数据回写失败(不影响本次产物) run=%s tpl=%s", run_id, tpl_id, exc_info=True
)
except TemplateFillError:
logger.warning("模板参考转换失败,回退默认数据 run=%s tpl=%s", run_id, tpl_id, exc_info=True)
data_obj = template_fill.reference_data(tpl_id)
@@ -14,6 +14,12 @@ HTML 模板需要的 ``DATA`` 结构后,本模块负责把数据**填充**进模
行内无换行),所以用 ``^const VAR=.*;$`` (MULTILINE) 精确命中该行整体替换,绝不
误伤模板里别处出现的同名子串。替换值用函数回调写入,避开 ``re.sub`` 把 JSON 里的
反斜杠当反向引用的坑。
* **结构化模板(kind="structured")**: no.1 起引入 page-generator 范式——目录含
``template.html``(骨架,带 :data:`STRUCTURED_MARKERS` 注入标记)/``runtime.js``
(渲染逻辑 + 页面内 JSON 编辑器)/``data.json``(默认数据,兼作转换契约)/可选
``manifest.json``。填充走 :func:`compose_structured` 标记组合,产物仍是自包含
单文件 HTML;``reference_data`` 读 ``data.json``,与单文件模板的契约/校验/合并
语义完全一致。
* **harness 层、零 app.* 依赖**:可被调度器(harness)与 Gateway 路由(app)共同 import。
公开入口:``list_templates`` / ``get_template`` / ``reference_data`` /
@@ -107,6 +113,14 @@ def extract_embedded_json(text: str | None) -> Any | None:
# 模板资源根目录(随 git 发布,与本模块同级 ``templates/`` 子目录)。
_TEMPLATES_ROOT = Path(__file__).parent / "templates"
# 结构化模板骨架里的三个注入标记(compose_structured 逐个替换)。
DATA_MARKER = "__PAGE_DATA__"
MANIFEST_MARKER = "__PAGE_MANIFEST__"
RUNTIME_MARKER = "__PAGE_RUNTIME__"
STRUCTURED_MARKERS: tuple[str, ...] = (DATA_MARKER, MANIFEST_MARKER, RUNTIME_MARKER)
# 结构化模板目录里的组成文件(manifest.json 可选,其余必备)。
STRUCTURED_PARTS: tuple[str, ...] = ("template.html", "runtime.js", "data.json", "manifest.json")
@dataclass(frozen=True)
class TemplateSpec:
@@ -115,9 +129,20 @@ class TemplateSpec:
``file`` 相对 :data:`_TEMPLATES_ROOT`;``data_var``/``manifest_var`` 是模板里
待替换的 JS 常量名(``manifest_var`` 为空表示该模板没有 MANIFEST 行)。
``kind`` 有两种:
* ``"single"``(默认): 单文件模板,数据以 ``const DATA={…};`` 单行内嵌,填充 =
行级替换;
* ``"structured"``: 结构化模板(page-generator 范式),目录含
``template.html``(骨架,带 :data:`STRUCTURED_MARKERS` 三个注入标记)/
``runtime.js``(渲染 + 页面内 JSON 编辑器)/``data.json``(默认数据,即转换
契约)/可选 ``manifest.json``,填充 = 标记组合,产物仍是自包含单文件 HTML。
``legacy_file`` 指向单文件时代的随包正文,供 template_store 自动升级时做
「未被手改」的字节级比对。
``convertible=False`` 表示该模板暂只「直接展示已有数据」——执行时原样输出模板
HTML,不做 JSON 转换/校验/填充(无 ``const DATA=`` 注入行的模板用它,后续接入
转换后改回 True)。
转换后再改回 True)。
"""
id: str
@@ -127,6 +152,12 @@ class TemplateSpec:
data_var: str = "DATA"
manifest_var: str = ""
convertible: bool = True
kind: str = "single"
legacy_file: str = ""
@property
def structured(self) -> bool:
return self.kind == "structured"
# 已注册模板(随包 seed 源 + 存储缺失时的兜底注册表)。新增模板时在此追加一条
@@ -136,9 +167,14 @@ TEMPLATES: tuple[TemplateSpec, ...] = (
id="no1",
name="no.1",
description="",
file="no1/taiwan_littoral_ui_redwhite_v2.html",
file="no1/template.html",
data_var="DATA",
manifest_var="MANIFEST",
# 结构化模板(page-generator 范式):骨架 + runtime + 默认数据 + MANIFEST,
# 填充走 compose_structured 标记组合;legacy_file 是单文件时代的随包正文,
# 供 template_store 把「未被手改」的旧存储副本自动升级到结构化版。
kind="structured",
legacy_file="no1/taiwan_littoral_ui_redwhite_v2.html",
),
TemplateSpec(
id="no2",
@@ -401,6 +437,7 @@ def get_template(template_id: str) -> TemplateSpec | None:
data_var="DATA",
manifest_var=str(meta.get("manifest_var") or ""),
convertible=bool(meta.get("convertible")),
kind=str(meta.get("kind") or "single"),
)
return _TEMPLATES_BY_ID.get(template_id)
@@ -435,8 +472,122 @@ def _template_path(spec: TemplateSpec) -> Path:
return _TEMPLATES_ROOT / spec.file
# ── 结构化模板(骨架 + runtime + 数据分文件,组合成单文件产物) ────────────────
def _structured_part(template_id: str, name: str) -> Path | None:
"""结构化模板某个组成文件的路径:存储副本优先,随包文件兜底;都没有返回 None。
``manifest.json`` 可选;其余文件缺失属打包损坏,由 :func:`_structured_text` 报错。
"""
from deerflow.runtime.scheduler import template_store
store_file = template_store.store_root() / template_id / name
if store_file.is_file():
return store_file
fallback = _TEMPLATES_ROOT / template_id / name
return fallback if fallback.is_file() else None
def _structured_text(template_id: str, name: str) -> str:
path = _structured_part(template_id, name)
if path is None:
raise TemplateError(f"结构化模板文件缺失:{template_id}/{name}")
return path.read_text(encoding="utf-8")
def _read_default_manifest(template_id: str) -> dict[str, Any]:
"""结构化模板的默认 MANIFEST;没有 manifest.json 时返回空对象。"""
path = _structured_part(template_id, "manifest.json")
if path is None:
return {}
try:
obj = json.loads(path.read_text(encoding="utf-8"))
except (OSError, ValueError) as exc:
raise TemplateError(f"解析 {template_id}/manifest.json 失败:{exc}") from exc
return obj if isinstance(obj, dict) else {}
def structured_module_labels(template_id: str) -> list[dict[str, str]]:
"""结构化模板各数据模块(DATA 顶层键)的中文显示名,管理页「编辑数据」用。
标签来源按优先级:MANIFEST.页面 的「编号」精确命中 → 「数据源/架构数据」去掉
``data/`` 前缀和 ``.json`` 后缀后命中(如 organization_charts) → 编号按 ``_``
拆分后命中任一段(如 events/projects 命中 events_projects)。都没有则回退键名。
"""
ref = reference_data(template_id)
manifest = _read_default_manifest(template_id)
labels: dict[str, str] = {}
split_index: dict[str, str] = {}
pages = manifest.get("页面")
if isinstance(pages, list):
for page in pages:
if not isinstance(page, dict):
continue
name = str(page.get("名称") or "").strip()
if not name:
continue
candidates: list[str] = []
for field in ("编号", "数据源", "架构数据"):
raw = str(page.get(field) or "").strip()
if not raw:
continue
key = raw.removeprefix("data/").removesuffix(".json")
if key:
candidates.append(key)
for key in candidates:
labels[key] = name
first = candidates[0] if candidates else ""
if first and "_" in first:
for part in first.split("_"):
if part:
split_index[part] = name
out: list[dict[str, str]] = []
for key in ref:
out.append({"key": key, "label": labels.get(key) or split_index.get(key) or key})
return out
def compose_structured(
*,
skeleton: str,
runtime: str,
data: Any,
manifest: dict[str, Any] | None = None,
) -> str:
"""把数据/运行时按标记组合进骨架,产出自包含单文件 HTML。
与 page-generator 技能的 render 脚本同一套安全转义:数据 JSON 里的 ``</`` →
``<\\/``(JSON 字符串里 ``\\/`` 合法),runtime 里的 ``</script`` → ``<\\/script``,
防止内容提前闭合 script 标签。组合后断言无残留标记。
"""
serialized_data = json.dumps(data, ensure_ascii=False).replace("</", "<\\/")
out = skeleton.replace(DATA_MARKER, serialized_data)
if MANIFEST_MARKER in out:
serialized_manifest = (
json.dumps(manifest, ensure_ascii=False).replace("</", "<\\/")
if manifest is not None
else "{}"
)
out = out.replace(MANIFEST_MARKER, serialized_manifest)
out = out.replace(RUNTIME_MARKER, runtime.replace("</script", "<\\/script"))
residual = [m for m in STRUCTURED_MARKERS if m in out]
if residual:
raise TemplateError(f"结构化模板组合后仍残留标记:{'、'.join(residual)}")
return out
def read_template_text(template_id: str) -> str:
spec = _require(template_id)
if spec.structured:
# 结构化模板对外始终呈现「组合后的完整文档」(预览/只展示/参考展示共用);
# 骨架原文(编辑用)由 template_store.read_template_html 直接读文件。
return compose_structured(
skeleton=_structured_text(template_id, "template.html"),
runtime=_structured_text(template_id, "runtime.js"),
data=reference_data(template_id),
manifest=_read_default_manifest(template_id),
)
path = _template_path(spec)
if not path.is_file():
raise TemplateError(f"模板文件缺失:{path}")
@@ -464,8 +615,22 @@ def _extract_const_object(text: str, var: str) -> Any:
@lru_cache(maxsize=16)
def reference_data(template_id: str) -> dict[str, Any]:
"""模板内嵌的参考 ``DATA`` 对象(目标格式范例 + 校验基准),按模板缓存。"""
"""模板内嵌的参考 ``DATA`` 对象(目标格式范例 + 校验基准),按模板缓存。
单文件模板解析 ``const DATA=`` 行;结构化模板直接读 ``data.json``(两者语义一致:
顶层键即子页面,validate_data/merge_with_reference/骨架 prompt 全部通用)。
"""
spec = _require(template_id)
if spec.structured:
try:
obj = json.loads(_structured_text(template_id, "data.json"))
except OSError as exc:
raise TemplateError(f"读取 {template_id}/data.json 失败:{exc}") from exc
except ValueError as exc:
raise TemplateError(f"解析 {template_id}/data.json 失败:{exc}") from exc
if not isinstance(obj, dict):
raise TemplateError(f"模板 {template_id} 的 data.json 不是对象")
return obj
text = read_template_text(template_id)
obj = _extract_const_object(text, spec.data_var)
if not isinstance(obj, dict):
@@ -774,28 +939,18 @@ def pop_page_titles(obj: dict[str, Any]) -> tuple[str | None, str | None]:
return title, subtitle
def fill_template(
template_id: str,
data_obj: Any,
*,
manifest_overrides: dict[str, Any] | None = None,
update_date: date | None = None,
title: str | None = None,
subtitle: str | None = None,
) -> str:
"""把 ``data_obj`` 填进模板的 ``const DATA=…`` 行,产出完整 HTML 文档。
def _apply_page_titles(
text: str,
title: str | None,
subtitle: str | None,
manifest_overrides: dict[str, Any] | None,
) -> tuple[str, dict[str, Any] | None]:
"""替换页头静态标题/副标题;给出 title 时同步返回含 ``系统.名称`` 的 overrides。
可选地更新 MANIFEST 的「系统.更新时间」(``update_date``,默认不动) 以及任意
``manifest_overrides``(深合并到解析后的 MANIFEST,如改系统名称)。
``title``/``subtitle`` 来自转换结果里的「页面标题/页面副标题」:模板页头
(<title>、第一个 <h1>、其后紧跟的副标题 <p>)是写死的静态 HTML,不随 DATA
变化——给出新标题时替换这三处,并把 MANIFEST 的 系统.名称 一并同步;
不给则保持模板原文。
模板页头(``<title>``、第一个 ``<h1>``、其后紧跟的副标题 ``<p>``)是写死的静态
HTML,不随 DATA 变化——给出新标题时替换这两处,并把 MANIFEST 的 系统.名称 一并
同步;不给则保持模板原文。单文件/结构化两条填充路径共用。
"""
spec = _require(template_id)
text = read_template_text(template_id)
if title:
overrides = dict(manifest_overrides or {})
system = overrides.get("系统")
@@ -815,6 +970,70 @@ def fill_template(
count=1,
flags=re.DOTALL,
)
return text, manifest_overrides
def _fill_structured(
template_id: str,
data_obj: Any,
*,
manifest_overrides: dict[str, Any] | None,
update_date: date | None,
title: str | None,
subtitle: str | None,
) -> str:
"""结构化模板填充:标记组合出完整单文件 HTML(数据内嵌 JSON 元素 + runtime 内联)。"""
skeleton, manifest_overrides = _apply_page_titles(
_structured_text(template_id, "template.html"), title, subtitle, manifest_overrides
)
manifest = _read_default_manifest(template_id)
if update_date is not None:
system = manifest.get("系统")
if isinstance(system, dict):
system["更新时间"] = update_date.isoformat()
if manifest_overrides:
_deep_merge(manifest, manifest_overrides)
return compose_structured(
skeleton=skeleton,
runtime=_structured_text(template_id, "runtime.js"),
data=data_obj,
manifest=manifest,
)
def fill_template(
template_id: str,
data_obj: Any,
*,
manifest_overrides: dict[str, Any] | None = None,
update_date: date | None = None,
title: str | None = None,
subtitle: str | None = None,
) -> str:
"""把 ``data_obj`` 填进模板,产出完整 HTML 文档。
单文件模板:行级替换 ``const DATA=…``;结构化模板::func:`_fill_structured`
标记组合。可选地更新 MANIFEST 的「系统.更新时间」(``update_date``,默认不动)
以及任意 ``manifest_overrides``(深合并到解析后的 MANIFEST,如改系统名称)。
``title``/``subtitle`` 来自转换结果里的「页面标题/页面副标题」:模板页头
(<title>、第一个 <h1>、其后紧跟的副标题 <p>)是写死的静态 HTML,不随 DATA
变化——给出新标题时替换这三处,并把 MANIFEST 的 系统.名称 一并同步;
不给则保持模板原文。
"""
spec = _require(template_id)
if spec.structured:
return _fill_structured(
template_id,
data_obj,
manifest_overrides=manifest_overrides,
update_date=update_date,
title=title,
subtitle=subtitle,
)
text = read_template_text(template_id)
text, manifest_overrides = _apply_page_titles(text, title, subtitle, manifest_overrides)
data_re = _const_line_re(spec.data_var)
if data_re.search(text) is None:
@@ -5,17 +5,27 @@
升级为**文件型存储**,模板管理页与定时任务表单共用:
{base_dir}/html-templates/<id>/
├── template.html # 模板正文
└── meta.json # {id, name, description, builtin, convertible, manifest_var, created_at, updated_at}
├── template.html # 模板正文(单文件模板 = 完整文档;结构化模板 = 骨架)
├── runtime.js # 结构化模板:渲染逻辑 + 页面内 JSON 编辑器(可选件)
├── data.json # 结构化模板:默认数据,兼作转换契约(可选件)
├── manifest.json # 结构化模板:系统/页面/交互规则(可选件)
└── meta.json # {id, name, description, builtin, kind, convertible, manifest_var, created_at, updated_at}
设计要点
--------
* **seed 不覆盖**:{base_dir}/html-templates/<id>/ 目录缺失时才从随包模板复制(与
``_template_builder_seed.py`` 同语义),线上/管理页的修改绝不会被启动 seed 回写。
* **convertible 自动探测**:写入(创建/改正文/重置)时扫描正文是否含可解析的内联
``const DATA={…};`` 行(当前填充引擎唯一支持的注入点)——有则该模板可「JSON 转换
填充」,无则「只展示」。上传带注入行的新模板即可零代码接入转换管线;探测同时认
``const MANIFEST=`` 行并记入 meta,``fill_template`` 的更新时间/标题替换可生效。
**例外——结构化自动升级**:注册表条目升级为 ``kind="structured"`` 后,若存储里的
旧单文件副本与随包 ``legacy_file`` 字节一致(即从未被手改),启动时自动重建为
结构化版;改过的保留旧版,由管理页「重置」手动升级。
* **convertible 自动探测**(单文件模板):写入(创建/改正文/重置)时扫描正文是否含
可解析的内联 ``const DATA={…};`` 行——有则该模板可「JSON 转换填充」,无则「只展示」。
结构化模板的 convertible/manifest_var 以注册表/``data.json`` 为准,不靠正文探测。
* **结构化模板的数据持久化**:``read_template_data`` / ``write_template_data`` 支撑
管理页「编辑数据」——整体替换 ``data.json``,替换前经
:func:`template_fill.validate_data` 契约校验(顶层键不可增删),改契约先改模板。
编辑结构化正文仅允许改骨架,且必须保留 :data:`template_fill.STRUCTURED_MARKERS`
三个注入标记。
* **内置模板可改不可删**:删除会把引用它的定时任务全部弄挂,内置模板(builtin)
只允许编辑/上传覆盖/重置回随包原版,自建模板可删。
* harness 层、零 app.* 依赖:调度器与 Gateway 路由共同 import;所有写操作都会
@@ -114,42 +124,84 @@ def _validate_html(html: str) -> str:
def ensure_seeded() -> bool:
"""把随包内置模板 seed 进存储;目录已存在(尊重管理页修改)则跳过。
返回 True 表示本次至少复制了一个模板。任何单模板失败只影响该模板,不抛出。
结构化模板多一步**自动升级**:注册表条目已是 ``kind="structured"`` 而存储 meta
还没有 kind(单文件时代的旧副本)时,若旧副本正文与随包 ``legacy_file`` 字节一致
(从未手改)则重建为结构化版;改过的保留,由管理页「重置」手动升级。
返回 True 表示本次至少新建/升级了一个模板。任何单模板失败只影响该模板,不抛出。
"""
created = False
changed = False
for spec in template_fill.TEMPLATES:
try:
tpl_dir = store_root() / spec.id
if tpl_dir.exists():
if spec.structured:
changed |= _maybe_upgrade_structured(spec)
continue
tpl_dir.mkdir(parents=True, exist_ok=True)
src = template_fill._TEMPLATES_ROOT / spec.file
html = src.read_text(encoding="utf-8")
(tpl_dir / "template.html").write_text(html, encoding="utf-8")
now = _now_iso()
(tpl_dir / "meta.json").write_text(
json.dumps(
{
"id": spec.id,
"name": spec.name,
"description": spec.description,
"builtin": True,
"convertible": spec.convertible,
"manifest_var": spec.manifest_var,
"created_at": now,
"updated_at": now,
},
ensure_ascii=False,
indent=1,
),
encoding="utf-8",
)
created = True
_seed_spec_dir(spec, tpl_dir)
changed = True
except Exception:
continue
if created:
if changed:
template_fill.invalidate_cache()
return created
return changed
def _seed_spec_dir(spec: Any, tpl_dir: Path) -> None:
"""按注册表条目把一个内置模板 seed 进存储目录(调用方保证目录不存在)。"""
tpl_dir.mkdir(parents=True, exist_ok=True)
src_root = template_fill._TEMPLATES_ROOT / spec.id
if spec.structured:
# 必备件缺失属打包损坏:抛错由 ensure_seeded 按单模板吞掉。
for name in ("template.html", "runtime.js", "data.json"):
(tpl_dir / name).write_text(
(src_root / name).read_text(encoding="utf-8"), encoding="utf-8"
)
for name in ("manifest.json", "fields.json"):
optional = src_root / name
if optional.is_file():
(tpl_dir / name).write_text(
optional.read_text(encoding="utf-8"), encoding="utf-8"
)
else:
src = template_fill._TEMPLATES_ROOT / spec.file
(tpl_dir / "template.html").write_text(
src.read_text(encoding="utf-8"), encoding="utf-8"
)
_write_meta(
spec.id,
{
"id": spec.id,
"name": spec.name,
"description": spec.description,
"builtin": True,
"kind": spec.kind,
"convertible": spec.convertible,
"manifest_var": spec.manifest_var,
},
keep_created=False,
)
def _maybe_upgrade_structured(spec: Any) -> bool:
"""旧单文件存储副本 → 结构化版(仅当正文与随包 legacy 文件字节一致,即从未手改)。"""
tpl_dir = store_root() / spec.id
if not tpl_dir.is_dir() or not spec.legacy_file:
return False
if _load_meta(tpl_dir).get("kind"):
return False # 已是结构化
legacy = template_fill._TEMPLATES_ROOT / spec.legacy_file
current = tpl_dir / "template.html"
if not legacy.is_file() or not current.is_file():
return False
try:
if legacy.read_bytes() != current.read_bytes():
return False # 线上手改过 → 保留旧版,「重置」手动升级
except OSError:
return False
shutil.rmtree(tpl_dir)
_seed_spec_dir(spec, tpl_dir)
return True
# ── 读取 ─────────────────────────────────────────────────────────────────────
@@ -169,8 +221,9 @@ def _load_meta(tpl_dir: Path) -> dict[str, Any]:
def list_templates() -> list[dict[str, Any]]:
"""存储内全部模板(内置按注册表顺序在前,自建按创建时间在后)。
返回条目:id/name/description/builtin/convertible/manifest_var/size/created_at/
updated_at;正文缺失的目录跳过(半成品不进下拉)。
返回条目:id/name/description/builtin/kind/convertible/manifest_var/size/created_at/
updated_at;正文缺失的目录跳过(半成品不进下拉)。结构化模板的 size 汇总
template.html+runtime.js+data.json+manifest.json。
"""
ensure_seeded()
root = store_root()
@@ -184,15 +237,24 @@ def list_templates() -> list[dict[str, Any]]:
if not html_file.is_file():
continue
meta = _load_meta(tpl_dir)
kind = str(meta.get("kind") or "single")
size = html_file.stat().st_size
if kind == "structured":
size += sum(
(tpl_dir / name).stat().st_size
for name in ("runtime.js", "data.json", "manifest.json")
if (tpl_dir / name).is_file()
)
entries.append(
{
"id": tpl_dir.name,
"name": str(meta.get("name") or tpl_dir.name),
"description": meta.get("description") or "",
"builtin": bool(meta.get("builtin")),
"kind": kind,
"convertible": bool(meta.get("convertible")),
"manifest_var": str(meta.get("manifest_var") or ""),
"size": html_file.stat().st_size,
"size": size,
"created_at": meta.get("created_at"),
"updated_at": meta.get("updated_at"),
}
@@ -215,12 +277,286 @@ def get_template_meta(template_id: str) -> dict[str, Any] | None:
def read_template_html(template_id: str) -> str:
"""模板正文**原文**(结构化模板 = 带 __PAGE_* 标记的骨架,非完整可预览文档)。
需要结构化模板的完整文档(预览/只展示)请用
:func:`template_fill.read_template_text`,它会把默认数据与 runtime 组合进去。
"""
path = store_template_file(template_id)
if not path.is_file():
raise TemplateStoreError(f"模板不存在:{template_id}")
return path.read_text(encoding="utf-8")
# ── 结构化模板数据(data.json)的读写(管理页「编辑数据」持久化) ────────────────
def _require_structured(template_id: str) -> dict[str, Any]:
entry = get_template_meta(template_id)
if entry is None:
raise TemplateStoreError(f"模板不存在:{template_id}")
if str(entry.get("kind") or "single") != "structured":
raise TemplateStoreError(f"模板不是结构化模板,不支持编辑数据:{template_id}")
return entry
def read_template_data(template_id: str) -> dict[str, Any]:
"""结构化模板的默认数据(data.json);存储缺文件时按引擎同一回退读随包。"""
_require_structured(template_id)
path = store_root() / template_id / "data.json"
if not path.is_file():
return template_fill.reference_data(template_id)
try:
obj = json.loads(path.read_text(encoding="utf-8"))
except (OSError, ValueError) as exc:
raise TemplateStoreError(f"读取 data.json 失败:{exc}") from exc
if not isinstance(obj, dict):
raise TemplateStoreError("data.json 不是 JSON 对象")
return obj
def read_template_manifest(template_id: str) -> dict[str, Any]:
"""结构化模板的 MANIFEST(manifest.json,系统名称/导航页面/交互规则);缺失返回空对象。"""
_require_structured(template_id)
path = store_root() / template_id / "manifest.json"
if not path.is_file():
return {}
try:
obj = json.loads(path.read_text(encoding="utf-8"))
except (OSError, ValueError) as exc:
raise TemplateStoreError(f"读取 manifest.json 失败:{exc}") from exc
if not isinstance(obj, dict):
raise TemplateStoreError("manifest.json 不是 JSON 对象")
return obj
def _dump_json_checked(obj: Any, label: str) -> str:
payload = json.dumps(obj, ensure_ascii=False)
encoded = payload.encode("utf-8")
if len(encoded) > MAX_HTML_BYTES:
raise TemplateStoreError(
f"{label}过大({len(encoded)} 字节,上限 {MAX_HTML_BYTES} 字节)"
)
return payload
def write_template_data(
template_id: str,
data_obj: Any,
*,
manifest: dict[str, Any] | None = None,
) -> dict[str, Any]:
"""整体替换结构化模板的默认数据(可选一并替换 MANIFEST)并清缓存;返回更新后的 meta。
data.json 替换前经 :func:`template_fill.validate_data` 契约校验(顶层键不可增删);
``manifest`` 给出时整体替换 manifest.json(系统名称/导航页面/交互规则的持久化入口)。
"""
_require_structured(template_id)
if not isinstance(data_obj, dict):
raise TemplateStoreError("数据必须是 JSON 对象")
errors = template_fill.validate_data(template_id, data_obj)
if errors:
raise TemplateStoreError(
"数据未通过模板契约校验(顶层键须与现有契约一致):" + ";".join(errors)
)
payload = _dump_json_checked(data_obj, "数据")
(store_root() / template_id / "data.json").write_text(payload, encoding="utf-8")
if manifest is not None:
if not isinstance(manifest, dict):
raise TemplateStoreError("MANIFEST 必须是 JSON 对象")
(store_root() / template_id / "manifest.json").write_text(
_dump_json_checked(manifest, "MANIFEST"), encoding="utf-8"
)
_write_meta(template_id, _load_meta(store_root() / template_id), keep_created=True)
template_fill.invalidate_cache()
return get_template_meta(template_id) # type: ignore[return-value]
# ── 字段显示 / 自定义模块(manifest 增量配置,字段目录读 fields.json) ─────────
def read_template_fields(template_id: str) -> list[dict[str, Any]]:
"""结构化模板的字段目录(fields.json:label/pages/description);没有目录返回空表。"""
_require_structured(template_id)
for base in (store_root() / template_id, template_fill._TEMPLATES_ROOT / template_id):
path = base / "fields.json"
if path.is_file():
try:
obj = json.loads(path.read_text(encoding="utf-8"))
except (OSError, ValueError) as exc:
raise TemplateStoreError(f"读取 fields.json 失败:{exc}") from exc
fields = obj.get("fields") if isinstance(obj, dict) else None
if isinstance(fields, list):
return [f for f in fields if isinstance(f, dict) and f.get("label")]
return []
return []
def _write_manifest_section(
template_id: str, key: str, value: Any, *, validate=None
) -> dict[str, Any]:
"""更新 manifest.json 的单个顶层键(其余原样保留)并清引擎缓存;返回更新后的 meta。
``validate(value)`` 可选,抛 TemplateStoreError 时拒绝写入。
"""
_require_structured(template_id)
manifest = read_template_manifest(template_id)
if validate is not None:
validate(value)
manifest[key] = value
(store_root() / template_id / "manifest.json").write_text(
_dump_json_checked(manifest, "MANIFEST"), encoding="utf-8"
)
_write_meta(template_id, _load_meta(store_root() / template_id), keep_created=True)
template_fill.invalidate_cache()
return get_template_meta(template_id) # type: ignore[return-value]
def write_template_field_visibility(
template_id: str, hidden_labels: list[str]
) -> dict[str, Any]:
"""字段显示/隐藏配置:manifest 的「字段显示」记 {label: false}(未记录=显示)。
标签须来自字段目录(fields.json),防止把「系统设置」里的同名键写坏。
"""
catalog = {f["label"] for f in read_template_fields(template_id)}
unknown = [x for x in hidden_labels if x not in catalog]
if unknown:
raise TemplateStoreError("未知字段:" + "、".join(unknown[:5]))
hidden = {label: False for label in hidden_labels}
return _write_manifest_section(template_id, "字段显示", hidden)
def write_template_field_locks(template_id: str, locked_labels: list[str]) -> dict[str, Any]:
"""字段「接受抽取更新」锁定名单:manifest「字段抽取关闭」记 {label: True}。
锁定后,定时任务抽取/写回不改该字段对应的数据键(保持模板现有数据);
名单为空 = 全部接受抽取更新(默认)。
"""
catalog = {f["label"] for f in read_template_fields(template_id)}
unknown = [x for x in locked_labels if x not in catalog]
if unknown:
raise TemplateStoreError("未知字段:" + "、".join(unknown[:5]))
locks = {label: True for label in locked_labels}
return _write_manifest_section(template_id, "字段抽取关闭", locks)
def locked_field_keys(template_id: str) -> set[str]:
"""被锁定(不接受抽取更新)字段对应的数据键集合;无锁定时为空集。"""
manifest = read_template_manifest(template_id)
locks = manifest.get("字段抽取关闭")
locks = locks if isinstance(locks, dict) else {}
if not any(v is True for v in locks.values()):
return set()
keys: set[str] = set()
for f in read_template_fields(template_id):
if locks.get(f["label"]) is True:
keys.update(str(k) for k in (f.get("keys") or []) if k)
return keys
def _item_identity(item: Any) -> str | None:
"""列表条目的身份键(id/编号/name/名称 取第一个非空),锁定恢复时按它匹配新旧条目。"""
if not isinstance(item, dict):
return None
for key in ("id", "编号", "name", "名称"):
value = item.get(key)
if isinstance(value, str) and value.strip():
return f"{key}:{value.strip()}"
if isinstance(value, (int, float)) and not isinstance(value, bool):
return f"{key}:{value}"
return None
def restore_locked_fields(template_id: str, data_obj: dict[str, Any]) -> dict[str, Any]:
"""把锁定字段的数据键恢复为模板现有值——抽取结果不覆盖,供调度器在
``merge_with_reference`` 之后、填充/写回之前调用。
列表分支按条目身份匹配新旧条目,匹配上才恢复(新条目保持抽取值);
对象分支(overview)逐键恢复。无锁定时原样返回。
"""
keys = locked_field_keys(template_id)
if not keys:
return data_obj
reference = template_fill.reference_data(template_id)
out = dict(data_obj)
for branch, new_val in data_obj.items():
old_val = reference.get(branch)
if isinstance(old_val, list) and isinstance(new_val, list):
old_index: dict[str, dict[str, Any]] = {}
for old_item in old_val:
if isinstance(old_item, dict):
ident = _item_identity(old_item)
if ident:
old_index[ident] = old_item
restored: list[Any] = []
for new_item in new_val:
if isinstance(new_item, dict):
ident = _item_identity(new_item)
old_item = old_index.get(ident) if ident else None
if old_item is not None:
merged = dict(new_item)
for key in keys:
if key in old_item:
merged[key] = old_item[key]
restored.append(merged)
continue
restored.append(new_item)
out[branch] = restored
elif isinstance(old_val, dict) and isinstance(new_val, dict):
merged = dict(new_val)
for key in keys:
if key in old_val:
merged[key] = old_val[key]
out[branch] = merged
return out
def write_template_custom_modules(
template_id: str, modules: list[dict[str, Any]]
) -> dict[str, Any]:
"""自定义模块列表(挂在指定页面底部的 AI 生成 HTML 片段)整体替换。
每项 {编号, 页面, 标题, html};html 经 :func:`sanitize_html_fragment` 消毒
(去 script/事件属性/javascript: 链接)后才允许入库。
"""
def _validate(value: Any) -> None:
if not isinstance(value, list):
raise TemplateStoreError("自定义模块必须是数组")
for i, item in enumerate(value):
if not isinstance(item, dict):
raise TemplateStoreError(f"自定义模块[{i}]必须是对象")
page = str(item.get("页面") or "").strip()
if not page:
raise TemplateStoreError(f"自定义模块[{i}]缺少「页面」")
html = str(item.get("html") or "").strip()
if not html:
raise TemplateStoreError(f"自定义模块[{i}]缺少内容 html")
item["html"] = sanitize_html_fragment(html)
return _write_manifest_section(template_id, "自定义模块", modules, validate=_validate)
# 自定义模块 HTML 片段消毒:去 <script>/<style 事件>/on* 事件属性/javascript: 链接。
_SCRIPT_TAG_RE = re.compile(r"<\s*/?\s*script\b[^>]*>", re.IGNORECASE)
_SCRIPT_BLOCK_RE = re.compile(r"<\s*script\b.*?<\s*/\s*script\s*>", re.IGNORECASE | re.DOTALL)
_ON_ATTR_RE = re.compile(r"\son[a-zA-Z]+\s*=\s*(?:\"[^\"]*\"|'[^']*'|[^\s>]+)", re.IGNORECASE)
_JS_URL_RE = re.compile(
r"(href|src|action)\s*=\s*(\"[^\"]*javascript:[^\"]*\"|'[^']*javascript:[^']*'|javascript:[^\s>]*)",
re.IGNORECASE,
)
def sanitize_html_fragment(html: str) -> str:
"""自定义模块片段入库前的安全清洗(页面经 innerHTML 渲染,须无脚本可执行)。"""
out = _SCRIPT_BLOCK_RE.sub("", str(html or ""))
out = _SCRIPT_TAG_RE.sub("", out)
out = _ON_ATTR_RE.sub("", out)
out = _JS_URL_RE.sub("", out)
return out.strip()
# ── 写入 ─────────────────────────────────────────────────────────────────────
@@ -275,13 +611,27 @@ def update_template(
description: str | None = None,
html: str | None = None,
) -> dict[str, Any]:
"""编辑模板(名称/描述/正文任选;改正文时重新探测 convertible 并清引擎缓存)。"""
"""编辑模板(名称/描述/正文任选;改正文时重新探测 convertible 并清引擎缓存)。
结构化模板的正文编辑仅针对**骨架**,保存前校验三个注入标记齐全(删标记 = 断了
组合管线);其 convertible/manifest_var 不靠正文探测,保持原值。改默认数据请用
:func:`write_template_data`。
"""
entry = get_template_meta(template_id)
if entry is None:
raise TemplateStoreError(f"模板不存在:{template_id}")
structured = str(entry.get("kind") or "single") == "structured"
if html is not None:
html = _validate_html(html)
if structured:
missing = [m for m in template_fill.STRUCTURED_MARKERS if m not in html]
if missing:
raise TemplateStoreError(
"结构化模板骨架缺少注入标记:"
+ "、".join(missing)
+ "(编辑正文不可删除标记;改数据请用「编辑数据」)"
)
store_template_file(template_id).write_text(html, encoding="utf-8")
meta = _load_meta(store_root() / template_id)
@@ -292,7 +642,7 @@ def update_template(
meta["name"] = name
if description is not None:
meta["description"] = description.strip()
if html is not None:
if html is not None and not structured:
convertible, manifest_var = _detect_specs(html)
meta["convertible"] = convertible
meta["manifest_var"] = manifest_var
@@ -313,14 +663,31 @@ def delete_template(template_id: str) -> None:
def reset_template(template_id: str) -> dict[str, Any]:
"""把内置模板的正文重置回随包原版(meta 名称/描述保留,convertible 重新探测)。"""
"""把内置模板重置回随包原版(meta 名称/描述保留,convertible 重新按注册表)。
结构化模板重置全部组成文件(template.html/runtime.js/data.json/manifest.json)。
"""
seed = next((s for s in template_fill.TEMPLATES if s.id == template_id), None)
entry = get_template_meta(template_id)
if seed is None or entry is None:
raise TemplateStoreError(f"仅内置模板支持重置:{template_id}")
html = (template_fill._TEMPLATES_ROOT / seed.file).read_text(encoding="utf-8")
store_template_file(template_id).write_text(html, encoding="utf-8")
if seed.structured:
src_root = template_fill._TEMPLATES_ROOT / template_id
for name in ("template.html", "runtime.js", "data.json"):
(store_root() / template_id / name).write_text(
(src_root / name).read_text(encoding="utf-8"), encoding="utf-8"
)
for name in ("manifest.json", "fields.json"):
optional = src_root / name
if optional.is_file():
(store_root() / template_id / name).write_text(
optional.read_text(encoding="utf-8"), encoding="utf-8"
)
else:
html = (template_fill._TEMPLATES_ROOT / seed.file).read_text(encoding="utf-8")
store_template_file(template_id).write_text(html, encoding="utf-8")
meta = _load_meta(store_root() / template_id)
meta["kind"] = seed.kind
meta["convertible"] = seed.convertible
meta["manifest_var"] = seed.manifest_var
_write_meta(template_id, meta, keep_created=True)
@@ -0,0 +1 @@
{"overview": {"核心指标": [{"名称": "综合区域", "数值": 9, "单位": "区", "说明": "覆盖本岛沿岸与主要离岛"}, {"名称": "组织与单位", "数值": 280, "单位": "个", "说明": "已去除组织与单位重复"}, {"名称": "单位深度档案", "数值": 179, "单位": "份", "说明": "已合并到对应组织节点"}, {"名称": "装备条目", "数值": 99, "单位": "项", "说明": "区分规划、采购、测试和列装"}, {"名称": "关键节点", "数值": 141, "单位": "个", "说明": "公共功能与韧性视角"}, {"名称": "演习与项目", "数值": 12, "单位": "项", "说明": "事件时间线与建设项目"}], "组织体系分布": [{"名称": "组织治理体系", "数值": 101}, {"名称": "海巡", "数值": 43}, {"名称": "全民动员", "数值": 29}, {"名称": "国防与联合体系", "数值": 28}, {"名称": "海军", "数值": 21}, {"名称": "陆军", "数值": 18}, {"名称": "空军", "数值": 16}, {"名称": "公共支援", "数值": 16}, {"名称": "海军陆战队", "数值": 8}], "装备类别分布": [{"名称": "无人系统", "数值": 12}, {"名称": "防空", "数值": 11}, {"名称": "海军平台", "数值": 10}, {"名称": "海巡平台", "数值": 9}, {"名称": "航空", "数值": 8}, {"名称": "地面火力", "数值": 7}, {"名称": "装甲", "数值": 5}, {"名称": "雷达与感知", "数值": 5}, {"名称": "反装甲", "数值": 4}, {"名称": "反舰", "数值": 3}, {"名称": "潜舰", "数值": 3}, {"名称": "反水雷", "数值": 3}, {"名称": "舰载防空", "数值": 3}, {"名称": "电子战", "数值": 3}, {"名称": "指挥控制", "数值": 3}, {"名称": "工程保障", "数值": 2}, {"名称": "布雷", "数值": 1}, {"名称": "综合支援", "数值": 1}, {"名称": "反无人机", "数值": 1}, {"名称": "无人水面平台", "数值": 1}, {"名称": "通信", "数值": 1}, {"名称": "机动运输", "数值": 1}, {"名称": "防护", "数值": 1}, {"名称": "医疗保障", "数值": 1}], "节点类别分布": [{"名称": "港口与海运", "数值": 26}, {"名称": "供水", "数值": 22}, {"名称": "能源与燃料", "数值": 18}, {"名称": "机场与航空", "数值": 17}, {"名称": "产业、物流与维修", "数值": 15}, {"名称": "陆路交通", "数值": 13}, {"名称": "医疗与救援", "数值": 11}, {"名称": "通信与数位韧性", "数值": 8}, {"名称": "应变指挥与警报", "数值": 6}, {"名称": "离岛持续保障", "数值": 5}], "业务入口": [{"页面": "regions", "名称": "沿岸区域", "数量": 9, "说明": "九区、县市与海岸分段"}, {"页面": "org_units", "名称": "组织与单位", "数量": 280, "说明": "组织架构图与单位深度档案"}, {"页面": "equipment", "名称": "武器装备", "数量": 99, "说明": "类别、体系、状态和公开作用"}, {"页面": "key_nodes", "名称": "关键节点", "数量": 141, "说明": "公共功能、依赖与替代"}, {"页面": "events_projects", "名称": "演习与项目", "数量": 12, "说明": "事件时间线和建设项目"}], "数据状态": {"知识库版本": "2.0", "页面版本": "2.0", "更新时间": "2026-06-23", "校验状态": "通过"}}, "regions": [{"region_id": "R01", "name": "北部沿岸", "scope": "基隆市、新北市沿岸及台北都会支撑区", "coastal_counties": ["基隆市", "新北市"], "support_areas": ["台北市", "桃园北部"], "coastal_morphology": ["野柳—东北角岬湾岩岸", "基隆港湾与人工港岸", "淡水河口沙岸与河口湿地", "八里—林口台地前缘海岸"], "segment_ids": ["S-R01-01", "S-R01-02", "S-R01-03", "S-R01-04", "S-R01-05"], "source_ids": ["SRC-WRA-TAIPEI-COAST", "SRC-TIPC-PORTS-2026", "SRC-CGA-ORG-2024", "SRC-CAA-AIRPORTS-2024"], "last_verified": "2026-06-23", "safety": "aggregate_only", "编号": "R01", "名称": "北部沿岸", "沿海县市": ["基隆市", "新北市"], "支撑区域": ["台北市", "桃园北部"], "海岸形态": ["野柳—东北角岬湾岩岸", "基隆港湾与人工港岸", "淡水河口沙岸与河口湿地", "八里—林口台地前缘海岸"], "县市子库": [{"county_id": "C-KEELUNG", "name": "基隆市", "region_id": "R01", "coastal_belt": ["基隆港城、外木山及东北角接口"], "dominant_functions": ["港口城市", "国际商港", "都会支撑"], "priority_risks": ["港城交通耦合", "强浪台风", "危险品与港区事故"], "last_verified": "2026-06-23", "safety": "aggregate_only"}, {"county_id": "C-NEWTAIPEI", "name": "新北市", "region_id": "R01", "coastal_belt": ["八里、林口、淡水、三芝、石门、金山、万里、瑞芳、贡寮"], "dominant_functions": ["台北港", "淡水河口", "北海岸观光渔业"], "priority_risks": ["海岸类型差异大", "跨都会交通", "东北角山区通道"], "last_verified": "2026-06-23", "safety": "aggregate_only"}], "海岸分段": [{"segment_id": "S-R01-01", "region_id": "R01", "name": "基隆港城段", Line truncated
@@ -0,0 +1,557 @@
{
"说明": "字段显示目录:控制页面详情字段/分区的显示与隐藏 + 是否接受定时任务抽取数据更新(keys=该字段对应的数据键;无 keys 为布局分区)。可见性存于 manifest「字段显示」,抽取锁定存于「字段抽取关闭」。",
"fields": [
{
"label": "上游依赖",
"pages": [
"关键节点"
],
"description": "该节点正常运行所依赖的上游设施",
"keys": [
"依赖类别"
]
},
{
"label": "主管或运营主体",
"pages": [
"关键节点"
],
"description": "节点的主管部门或运营单位",
"keys": [
"主管运营"
]
},
{
"label": "体系",
"pages": [
"组织与单位"
],
"description": "单位所属的组织治理体系分类",
"keys": [
"体系"
]
},
{
"label": "使用体系",
"pages": [
"武器装备"
],
"description": "装备配属使用的组织体系",
"keys": [
"使用体系中文"
]
},
{
"label": "公共功能",
"pages": [
"关键节点"
],
"description": "节点承担的公共功能",
"keys": [
"公共功能"
]
},
{
"label": "公开作用",
"pages": [
"武器装备"
],
"description": "装备公开承认的作用与用途",
"keys": [
"公开作用"
]
},
{
"label": "公开状态",
"pages": [
"武器装备"
],
"description": "装备的公开状态(在役、测试、规划等)",
"keys": [
"状态中文"
]
},
{
"label": "公开职掌与任务",
"pages": [
"组织与单位"
],
"description": "单位公开的职责与承担的任务",
"keys": [
"公开任务"
]
},
{
"label": "军令或任务上级",
"pages": [
"组织与单位"
],
"description": "其军令或任务线条上的上级单位",
"keys": [
"军令或任务上级"
]
},
{
"label": "分析限制",
"pages": [
"演习与项目"
],
"description": "对单次演习/项目的分析局限说明",
"keys": []
},
{
"label": "别名",
"pages": [
"武器装备"
],
"description": "装备的其它常用名称或编号",
"keys": [
"aliases"
]
},
{
"label": "区域",
"pages": [
"演习与项目"
],
"description": "与该条目相关的地理区域",
"keys": [
"区域中文"
]
},
{
"label": "区域、装备与演训关联",
"pages": [
"组织与单位"
],
"description": "与该单位相关的区域、装备及演习事件",
"keys": []
},
{
"label": "区域关联",
"pages": [
"组织与单位"
],
"description": "单位关联的沿岸区域",
"keys": [
"区域关联"
]
},
{
"label": "区域基本信息",
"pages": [
"沿岸区域"
],
"description": "区域的名称、编号与总体概况",
"keys": []
},
{
"label": "历史沿革与说明",
"pages": [
"组织与单位"
],
"description": "单位的历史变迁与补充说明",
"keys": [
"历史沿革"
]
},
{
"label": "县市子库",
"pages": [
"沿岸区域"
],
"description": "该区域包含的沿海县市清单",
"keys": [
"coastal_counties"
]
},
{
"label": "县市数量",
"pages": [
"沿岸区域"
],
"description": "该区域下辖沿海县市的具体数量",
"keys": [
"县市数量"
]
},
{
"label": "可信度",
"pages": [
"关键节点",
"武器装备",
"组织与单位"
],
"description": "该条信息的公开来源可信程度评价",
"keys": [
"可信度中文"
]
},
{
"label": "备注",
"pages": [
"武器装备"
],
"description": "补充备注信息",
"keys": [
"notes"
]
},
{
"label": "安全边界",
"pages": [
"组织与单位"
],
"description": "该类信息仅用于公共研究、不涉及敏感细节的边界说明",
"keys": []
},
{
"label": "当前状态",
"pages": [
"组织与单位"
],
"description": "单位当前的状态(运作、撤编等)",
"keys": [
"当前状态"
]
},
{
"label": "所属区域",
"pages": [
"关键节点"
],
"description": "节点所在的行政区域",
"keys": [
"区域中文"
]
},
{
"label": "支撑区域",
"pages": [
"沿岸区域"
],
"description": "该区域提供支撑保障的区域列表",
"keys": [
"支撑区域"
]
},
{
"label": "日期",
"pages": [
"演习与项目"
],
"description": "事件或项目发生的日期",
"keys": [
"日期显示"
]
},
{
"label": "替代与备援",
"pages": [
"关键节点"
],
"description": "节点故障时的替代与备援方案",
"keys": [
"替代备援"
]
},
{
"label": "来源",
"pages": [
"关键节点",
"武器装备",
"演习与项目"
],
"description": "资料出处(公开报道、官方文件等)",
"keys": [
"来源信息"
]
},
{
"label": "来源与核实",
"pages": [
"组织与单位"
],
"description": "资料出处以及核实情况的说明",
"keys": []
},
{
"label": "来源数量",
"pages": [
"组织与单位"
],
"description": "该条信息引用的公开来源数量",
"keys": [
"来源"
]
},
{
"label": "架构层级",
"pages": [
"组织与单位"
],
"description": "单位在组织架构中的层级",
"keys": [
"架构层级"
]
},
{
"label": "核实日期",
"pages": [
"武器装备",
"沿岸区域",
"组织与单位"
],
"description": "信息最近一次核实的时间",
"keys": [
"核实日期"
]
},
{
"label": "沿海县市",
"pages": [
"沿岸区域"
],
"description": "区域内的沿海县市名称列表",
"keys": [
"沿海县市"
]
},
{
"label": "海岸分段数量",
"pages": [
"沿岸区域"
],
"description": "海岸线被划分成研究分段的数目",
"keys": [
"分段数量"
]
},
{
"label": "海岸形态",
"pages": [
"沿岸区域"
],
"description": "海岸的地理形态分类(如沙滩、礁岸等)",
"keys": [
"海岸形态"
]
},
{
"label": "海岸研究分段",
"pages": [
"沿岸区域"
],
"description": "按海岸形态划分的研究分段明细",
"keys": [
"segment_ids"
]
},
{
"label": "演训与事件",
"pages": [
"组织与单位"
],
"description": "与该单位相关的演习与事件",
"keys": [
"演训与事件"
]
},
{
"label": "状态",
"pages": [
"演习与项目"
],
"description": "当前状态(如进行中、已完成等)",
"keys": [
"状态中文"
]
},
{
"label": "生命周期解释",
"pages": [
"武器装备"
],
"description": "对装备所处生命周期阶段的解释说明",
"keys": []
},
{
"label": "直接下级机构或单位",
"pages": [
"组织与单位"
],
"description": "直接下辖的下级机构或单位列表",
"keys": [
"下级机构"
]
},
{
"label": "研究边界",
"pages": [
"关键节点",
"沿岸区域"
],
"description": "本页面内容的研究范围与不涉及事项说明",
"keys": []
},
{
"label": "空间范围",
"pages": [
"沿岸区域"
],
"description": "该区域覆盖的地理空间范围描述",
"keys": [
"scope"
]
},
{
"label": "组织与单位概况",
"pages": [
"组织与单位"
],
"description": "单位的基本属性概览",
"keys": []
},
{
"label": "组织关系",
"pages": [
"组织与单位"
],
"description": "单位的上级、下级与协作关系",
"keys": []
},
{
"label": "组织或单位类型",
"pages": [
"组织与单位"
],
"description": "条目的类型(机构、单位、节点档案等)",
"keys": [
"单位类型"
]
},
{
"label": "节点层级",
"pages": [
"关键节点"
],
"description": "节点在基础设施体系中的层级",
"keys": [
"层级中文"
]
},
{
"label": "节点概况",
"pages": [
"关键节点"
],
"description": "关键节点的基本属性概览",
"keys": []
},
{
"label": "节点类别",
"pages": [
"关键节点"
],
"description": "节点的类别(港口、能源、通信等)",
"keys": [
"类别中文"
]
},
{
"label": "行政上级",
"pages": [
"组织与单位"
],
"description": "行政隶属关系上的上级单位",
"keys": [
"行政上级"
]
},
{
"label": "装备概况",
"pages": [
"武器装备"
],
"description": "装备的基本属性概览",
"keys": []
},
{
"label": "装备类别",
"pages": [
"武器装备",
"组织与单位"
],
"description": "相关装备的类别划分",
"keys": [
"类别中文"
]
},
{
"label": "记录类别",
"pages": [
"组织与单位"
],
"description": "条目在库中的记录分类",
"keys": [
"记录类别"
]
},
{
"label": "资料来源",
"pages": [
"沿岸区域"
],
"description": "区域资料的公开来源",
"keys": []
},
{
"label": "资料缺口",
"pages": [
"组织与单位"
],
"description": "尚缺失、待补充的资料说明",
"keys": [
"资料缺口"
]
},
{
"label": "资料说明",
"pages": [
"关键节点"
],
"description": "资料的补充说明文字",
"keys": [
"note"
]
},
{
"label": "资料边界",
"pages": [
"武器装备"
],
"description": "装备资料仅基于公开信息的范围说明",
"keys": []
},
{
"label": "运行状态",
"pages": [
"关键节点"
],
"description": "节点当前的运行状态",
"keys": [
"状态中文"
]
},
{
"label": "适用范围",
"pages": [
"组织与单位"
],
"description": "该内容适用的范围",
"keys": [
"适用范围"
]
}
]
}
@@ -0,0 +1 @@
{"系统": {"名称": "台湾滨海防卫知识数据展示系统", "版本": "2.0", "知识库版本": "2.0", "更新时间": "2026-06-23", "主题": {"模式": "红白", "主色": "#c8102e", "深红": "#8f1024", "浅红": "#fff1f3", "背景": "#f7f7f8", "卡片": "#ffffff", "文字": "#262626"}}, "页面": [{"编号": "overview", "名称": "总览", "数据源": "data/overview.json"}, {"编号": "regions", "名称": "沿岸区域", "数据源": "data/regions.json"}, {"编号": "org_units", "名称": "组织与单位", "数据源": "data/org_units.json", "架构数据": "data/organization_charts.json"}, {"编号": "equipment", "名称": "武器装备", "数据源": "data/equipment.json"}, {"编号": "key_nodes", "名称": "关键节点", "数据源": "data/key_nodes.json"}, {"编号": "events_projects", "名称": "演习与项目", "数据源": "data/events_projects.json"}], "交互规则": {"默认展示": "卡片与图形化面板", "列表限制": "不超过六个核心字段", "快速预览": "右侧抽屉", "复杂档案": "二级详情页", "长数组": "分组卡片或弹框", "查询": "各页面独立关键词、分类筛选和组合条件查询", "禁止展示": ["精确坐标", "实时部署", "兵力库存", "通信拓扑", "行动路线", "脆弱点排序"]}}
@@ -0,0 +1,336 @@
/* no.1 页面运行时(结构化模板)。
* 由 template_fill.compose_structured 内联进骨架的运行时注入点。
* 数据从骨架里的两个 JSON 元素读取:
* DATA ← <script type="application/json" id="page-data">
* MANIFEST ← <script type="application/json" id="page-manifest">
* 渲染逻辑与单文件版一致(全局函数 + inline onclick),末尾附页面 JSON 编辑器。 */
const DATA=JSON.parse(document.getElementById("page-data").textContent);
const MANIFEST=JSON.parse(document.getElementById("page-manifest").textContent);
const QUERY_SCHEMA={"版本": "2.0", "说明": "前端以中文条件构造器生成内部查询对象,不设置独立全库检索页面。", "查询域": {"沿岸区域": {"数据源": "regions", "字段": [{"字段": "名称", "显示名": "区域名称", "操作": ["包含", "等于"]}, {"字段": "沿海县市", "显示名": "沿海县市", "操作": ["包含"]}, {"字段": "海岸形态", "显示名": "海岸形态", "操作": ["包含"]}]}, "组织与单位": {"数据源": "org_units", "字段": [{"字段": "名称", "显示名": "名称", "操作": ["包含", "等于"]}, {"字段": "记录类别", "显示名": "记录类别", "操作": ["等于"]}, {"字段": "体系", "显示名": "体系", "操作": ["等于", "属于"]}, {"字段": "架构层级", "显示名": "架构层级", "操作": ["等于"]}, {"字段": "区域关联", "显示名": "区域关联", "操作": ["包含"]}, {"字段": "当前状态", "显示名": "当前状态", "操作": ["等于"]}]}, "武器装备": {"数据源": "equipment", "字段": [{"字段": "名称", "显示名": "装备名称", "操作": ["包含"]}, {"字段": "类别中文", "显示名": "装备类别", "操作": ["等于"]}, {"字段": "使用体系中文", "显示名": "使用体系", "操作": ["包含"]}, {"字段": "状态中文", "显示名": "公开状态", "操作": ["等于"]}]}, "关键节点": {"数据源": "key_nodes", "字段": [{"字段": "名称", "显示名": "节点名称", "操作": ["包含"]}, {"字段": "类别中文", "显示名": "节点类别", "操作": ["等于"]}, {"字段": "区域中文", "显示名": "所属区域", "操作": ["包含"]}, {"字段": "状态中文", "显示名": "运行状态", "操作": ["等于"]}]}, "演习与项目": {"数据源": "events_projects", "字段": [{"字段": "名称", "显示名": "名称", "操作": ["包含"]}, {"字段": "类型中文", "显示名": "事件类型", "操作": ["等于"]}, {"字段": "类别中文", "显示名": "项目类别", "操作": ["等于"]}, {"字段": "状态中文", "显示名": "状态", "操作": ["等于"]}]}}, "内部查询对象": {"数据域": "页面数据源编号", "关键词": "可选", "条件": [{"字段": "中文字段名", "操作": "包含或等于", "值": "查询值"}], "分页": {"页码": 1, "每页": 18}}};
const state={tab:"overview",mode:"chart",chart:"national_defense",q:"",filters:{},conditions:[],page:1,pageSize:18};
function e(v){return String(v??"").replace(/[&<>"']/g,m=>({"&":"&amp;","<":"&lt;",">":"&gt;",'"':"&quot;","'":"&#39;"}[m]))}
function a(v){return Array.isArray(v)?v:(v===undefined||v===null||v===""?[]:[v])}
function text(v){return Array.isArray(v)?v.join(" "):typeof v==="object"&&v?JSON.stringify(v):String(v??"")}
function chips(v,red=false,max=8){const x=a(v);return x.slice(0,max).map(y=>`<span class="chip ${red?"chip-red":""}">${e(y)}</span>`).join("")+(x.length>max?`<span class="chip">另${x.length-max}项</span>`:"")}
function statusChip(v){const green=/运行|列装|官方|确认|通过/.test(v||"");const orange=/规划|测试|建设|扩建|核验|有限/.test(v||"");return `<span class="chip ${green?"chip-green":orange?"chip-orange":"chip-red"}">${e(v||"未标注")}</span>`}
function unique(data,field){const s=new Set();data.forEach(x=>a(x[field]).forEach(v=>v&&s.add(v)));return [...s].sort()}
function setTab(tab){state.tab=tab;state.q="";state.filters={};state.conditions=[];state.page=1;location.hash="#/"+tab;render()}
function nav(){
document.getElementById("tabs").innerHTML=MANIFEST.页面.map(x=>`<button class="tab ${state.tab===x.编号?"active":""}" onclick="setTab('${x.编号}')">${x.名称}</button>`).join("")
}
function hero(title,desc,actions=""){return `<div class="hero"><div><h2>${title}</h2><p>${desc}</p><div style="margin-top:14px">${actions}</div></div><div class="hero-mark"></div></div>`}
function renderCustomModules(){
var list=a(MANIFEST.自定义模块).filter(function(m){return m&&m.页面===state.tab&&m.html});
if(!list.length)return;
var host=document.getElementById("customModules");
if(!host){host=document.createElement("div");host.id="customModules";document.getElementById("page").appendChild(host)}
host.innerHTML=list.map(function(m){return '<section class="detail-section" style="margin-top:16px"><h3>'+e(m.标题||"自定义模块")+'</h3>'+m.html+'</section>'}).join("")
}
function render(){nav();document.getElementById("page").style.display="block";document.getElementById("detailPage").classList.remove("show");const fn=window["render_"+state.tab]||render_overview;fn();renderCustomModules()}
function render_overview(){
const o=DATA.overview;
const metrics=o.核心指标.map(x=>`<div class="metric"><div class="metric-label">${x.名称}</div><div class="metric-value">${x.数值}<span class="metric-unit">${x.单位}</span></div><div class="metric-note">${x.说明}</div></div>`).join("");
const max=Math.max(...o.组织体系分布.map(x=>x.数值));
const bars=o.组织体系分布.slice(0,10).map(x=>`<div class="bar-row"><span>${e(x.名称)}</span><div class="bar"><i style="width:${x.数值/max*100}%"></i></div><b>${x.数值}</b></div>`).join("");
const entries=o.业务入口.map(x=>`<div class="entry-card" onclick="setTab('${x.页面}')"><b>${x.名称}</b><span class="entry-num">${x.数量}</span><p>${x.说明}</p></div>`).join("");
document.getElementById("page").innerHTML=hero("知识库业务总览","以区域、组织与单位、装备、公共关键节点、演习和建设项目为主线组织知识数据。")+
`<div class="metrics">${metrics}</div><div class="grid2"><div class="panel"><div class="panel-title"><span>组织体系分布</span></div>${bars}</div><div class="panel"><div class="panel-title"><span>业务入口</span></div><div class="entry-grid">${entries}</div></div></div>`;
}
function toolbar(domain,data,filterFields){
const selects=filterFields.map(f=>`<select data-filter="${f}"><option value="">${f}:全部</option>${unique(data,f).slice(0,120).map(v=>`<option value="${e(v)}" ${state.filters[f]===String(v)?"selected":""}>${e(v)}</option>`).join("")}</select>`).join("");
return `<div class="toolbar"><input id="keyword" value="${e(state.q)}" placeholder="输入关键词查询当前页面">${selects}<button class="btn btn-soft" onclick="openQueryBuilder('${domain}')">组合查询</button><button class="btn" onclick="clearQuery()">清空</button><span class="toolbar-count" id="count"></span></div>`;
}
function bindToolbar(domain,renderFn){
const q=document.getElementById("keyword");if(q)q.oninput=()=>{state.q=q.value;state.page=1;renderFn()};
document.querySelectorAll("[data-filter]").forEach(s=>s.onchange=()=>{state.filters[s.dataset.filter]=s.value;state.page=1;renderFn()});
}
function clearQuery(){state.q="";state.filters={};state.conditions=[];state.page=1;render()}
function matches(item,fields){
const q=state.q.trim().toLowerCase();
if(q&&!fields.some(f=>text(item[f]).toLowerCase().includes(q)))return false;
for(const [f,v] of Object.entries(state.filters)){if(v&&!a(item[f]).some(x=>String(x)===String(v)))return false}
for(const c of state.conditions){
const value=item[c.field],all=a(value);
if(c.op==="包含"&&!all.some(x=>String(x).includes(c.value)))return false;
if(c.op==="等于"&&!all.some(x=>String(x)===c.value))return false;
if(c.op==="属于"&&!all.some(x=>c.value.split(/[、,,]/).map(y=>y.trim()).includes(String(x))))return false;
}
return true
}
function paginate(items){const start=(state.page-1)*state.pageSize;return items.slice(start,start+state.pageSize)}
function pagination(total,rerender){const pages=Math.max(1,Math.ceil(total/state.pageSize));return `<div class="pagination"><button class="btn" ${state.page<=1?"disabled":""} onclick="state.page--;${rerender}">上一页</button><span class="page-no">第 ${state.page} / ${pages} 页</span><button class="btn" ${state.page>=pages?"disabled":""} onclick="state.page++;${rerender}">下一页</button></div>`}
function render_regions(){
const cards=DATA.regions.map(r=>`<article class="region-card" onclick="openDetail('regions','${r.编号}')"><h3>${r.编号} · ${r.名称}</h3><p>${e(r.档案摘要)}</p><div>${chips(r.海岸形态,true,3)}</div><div class="region-stats"><div><b>${r.县市数量}</b><br><small>县市子库</small></div><div><b>${r.分段数量}</b><br><small>海岸分段</small></div></div></article>`).join("");
document.getElementById("page").innerHTML=hero("沿岸区域","采用九个综合研究区,下钻到沿海县市和海岸研究分段。")+`<div class="region-grid">${cards}</div>`;
}
function render_org_units(){
const chartActive=state.mode==="chart",cardsActive=state.mode==="cards";
document.getElementById("page").innerHTML=hero("组织与单位","组织架构与单位档案使用同一套280个唯一节点。点击架构节点或机构卡片可进入完整档案。")+
`<div class="segmented"><button class="seg-btn ${chartActive?"active":""}" onclick="state.mode='chart';render_org_units()">组织架构图</button><button class="seg-btn ${cardsActive?"active":""}" onclick="state.mode='cards';render_org_units()">机构与单位卡片</button></div><div id="orgBody"></div>`;
if(chartActive)renderOrgChart();else renderOrgCards(true);
}
function renderOrgChart(){
const views=DATA.organization_charts;
const current=views.find(x=>x.id===state.chart)||views[0];
const buttons=views.map(x=>`<button class="chart-view ${x.id===current.id?"active":""}" onclick="state.chart='${x.id}';renderOrgChart()">${x.名称}</button>`).join("");
const tree=`<div class="org-chart"><ul><li>${chartNode(current.tree)}</li></ul></div>`;
const roots=DATA.org_units.filter(x=>!x.行政上级编号).length;
document.getElementById("orgBody").innerHTML=`<div class="chart-toolbar">${buttons}</div><div class="panel" style="margin-bottom:14px"><div class="panel-title"><span>${current.名称}</span></div><p style="color:#777;font-size:13px">${current.说明}</p></div><div class="summary-strip"><div class="summary-card"><b>${DATA.org_units.length}</b><span>唯一组织节点</span></div><div class="summary-card"><b>${DATA.org_units.filter(x=>x.记录类别==="单位").length}</b><span>含深度单位档案</span></div><div class="summary-card"><b>${DATA.org_units.filter(x=>x.记录类别==="机构").length}</b><span>制度与组织节点</span></div><div class="summary-card"><b>${roots}</b><span>顶层或独立根节点</span></div></div><div class="org-chart-wrap">${tree}</div>`;
}
function chartNode(n){
if(!n)return "";
const children=(n.children||[]).length?`<ul>${n.children.map(c=>`<li>${chartNode(c)}</li>`).join("")}</ul>`:"";
return `<div class="org-node" onclick="openDetail('org_units','${n.id}')"><b>${e(n.名称)}</b><small>${e(n.类型)}</small><div class="node-kind">${e(n.记录类别)} · ${e(n.状态)}</div></div>${children}`;
}
function renderOrgCards(initial=false){
const data=DATA.org_units;
if(initial){
document.getElementById("orgBody").innerHTML=toolbar("组织与单位",data,["记录类别","体系","架构层级","当前状态"])+`<div id="orgCards"></div>`;
bindToolbar("组织与单位",()=>renderOrgCards(false));
}
const filtered=data.filter(x=>matches(x,["名称","档案摘要","体系","架构层级","公开任务","区域关联","装备类别"]));
const cards=paginate(filtered).map(x=>`<article class="data-card" onclick="openDetail('org_units','${x.id}')"><div class="card-top"><div><h3>${e(x.名称)}</h3><div class="card-sub">${e(x.体系)} · ${e(x.架构层级)}</div></div><span class="card-type">${e(x.记录类别)}</span></div><p>${e(x.档案摘要)}</p><div class="card-roles">${a(x.公开任务).slice(0,2).map(y=>`<div class="role-line">${e(y)}</div>`).join("")}</div><div class="card-footer"><span>${e(x.行政上级)}</span><span>${e(x.当前状态)}</span></div></article>`).join("");
document.getElementById("orgCards").innerHTML=`<div class="card-grid">${cards||'<div class="empty">没有匹配结果</div>'}</div>${pagination(filtered.length,"renderOrgCards(false)")}`;
const count=document.getElementById("count");if(count)count.textContent=`共 ${filtered.length} 个节点`;
}
function categorySummary(data,field,onClick){
const counts={};data.forEach(x=>{const k=x[field]||"未分类";counts[k]=(counts[k]||0)+1});
return `<div class="category-grid">${Object.entries(counts).sort((a,b)=>b[1]-a[1]).slice(0,10).map(([k,v])=>`<div class="category-card" onclick="${onClick}('${e(k)}')"><b>${v}</b><span>${e(k)}</span></div>`).join("")}</div>`
}
function render_equipment(initial=true){
const data=DATA.equipment;
document.getElementById("page").innerHTML=hero("武器装备","以装备卡片展示类别、使用体系、公开作用和生命周期状态,不把规划、采购、测试和列装混为一谈。")+
categorySummary(data,"类别中文","filterEquipmentCategory")+toolbar("武器装备",data,["类别中文","状态中文","可信度中文"])+`<div id="equipmentCards"></div>`;
bindToolbar("武器装备",()=>renderEquipmentCards());
renderEquipmentCards();
}
function filterEquipmentCategory(v){state.filters["类别中文"]=v;state.page=1;render_equipment()}
function renderEquipmentCards(){
const data=DATA.equipment.filter(x=>matches(x,["名称","别名","类别中文","使用体系中文","公开作用","状态中文"]));
const html=paginate(data).map(x=>`<article class="data-card" onclick="openDetail('equipment','${x.id}')"><div class="card-top"><div><h3>${e(x.名称)}</h3><div class="card-sub">${e(x.类别中文)} · ${a(x.使用体系中文).join("、")}</div></div>${statusChip(x.状态中文)}</div><p>${e(x.档案摘要)}</p><div class="card-roles">${a(x.公开作用).slice(0,3).map(y=>`<div class="role-line">${e(y)}</div>`).join("")}</div><div class="card-footer"><span>可信度:${e(x.可信度中文)}</span><span>${e(x.verified_at||"未标注")}</span></div></article>`).join("");
document.getElementById("equipmentCards").innerHTML=`<div class="card-grid">${html||'<div class="empty">没有匹配结果</div>'}</div>${pagination(data.length,"renderEquipmentCards()")}`;
const c=document.getElementById("count");if(c)c.textContent=`共 ${data.length} 项装备`;
}
function render_key_nodes(){
const data=DATA.key_nodes;
document.getElementById("page").innerHTML=hero("关键节点","从公共功能和韧性角度展示港口、机场、交通、能源、通信、供水、医疗和产业节点。")+
categorySummary(data,"类别中文","filterNodeCategory")+toolbar("关键节点",data,["类别中文","层级中文","状态中文","可信度中文"])+`<div id="nodeCards"></div>`;
bindToolbar("关键节点",()=>renderNodeCards());renderNodeCards();
}
function filterNodeCategory(v){state.filters["类别中文"]=v;state.page=1;render_key_nodes()}
function renderNodeCards(){
const data=DATA.key_nodes.filter(x=>matches(x,["名称","类别中文","区域中文","主管运营","公共功能","状态中文"]));
const html=paginate(data).map(x=>`<article class="data-card" onclick="openDetail('key_nodes','${x.id}')"><div class="card-top"><div><h3>${e(x.名称)}</h3><div class="card-sub">${e(x.类别中文)} · ${e(x.层级中文)}</div></div>${statusChip(x.状态中文)}</div><p>${e(x.档案摘要)}</p><div>${chips(x.区域中文,true,3)}</div><div class="card-roles">${a(x.公共功能).slice(0,2).map(y=>`<div class="role-line">${e(y)}</div>`).join("")}</div><div class="card-footer"><span>${e(x.主管运营)}</span><span>可信度:${e(x.可信度中文)}</span></div></article>`).join("");
document.getElementById("nodeCards").innerHTML=`<div class="card-grid">${html||'<div class="empty">没有匹配结果</div>'}</div>${pagination(data.length,"renderNodeCards()")}`;
const c=document.getElementById("count");if(c)c.textContent=`共 ${data.length} 个节点`;
}
function render_events_projects(){
const events=DATA.events.map(x=>`<article class="time-card" onclick="openDetail('events','${x.id}')"><div class="time-date">${e(x.日期显示)}</div><h3 style="margin:0 0 7px">${e(x.名称)}</h3><div>${chips([x.类型中文,...a(x.区域中文)],true,4)}</div><p>${e(x.档案摘要)}</p></article>`).join("");
const projects=DATA.projects.map(x=>`<article class="data-card" onclick="openDetail('projects','${x.id}')"><div class="card-top"><div><h3>${e(x.名称)}</h3><div class="card-sub">${e(x.类别中文)}</div></div>${statusChip(x.状态中文)}</div><p>${e(x.档案摘要)}</p><div class="card-footer"><span>建设项目</span><span>${e(x.状态中文)}</span></div></article>`).join("");
document.getElementById("page").innerHTML=hero("演习与项目","演习采用时间线,建设项目采用卡片,分别表达日期型事件和生命周期型项目。")+
`<div class="grid2"><section class="panel"><div class="panel-title"><span>演习与重要事件</span></div><div class="timeline">${events}</div></section><section class="panel"><div class="panel-title"><span>现代化与建设项目</span></div><div class="card-grid" style="grid-template-columns:1fr">${projects}</div></section></div>`;
}
function findItem(domain,id){
if(domain==="regions")return DATA.regions.find(x=>x.编号===id);
if(domain==="org_units")return DATA.org_units.find(x=>x.id===id);
if(domain==="equipment")return DATA.equipment.find(x=>x.id===id);
if(domain==="key_nodes")return DATA.key_nodes.find(x=>x.id===id);
if(domain==="events")return DATA.events.find(x=>x.id===id);
if(domain==="projects")return DATA.projects.find(x=>x.id===id);
}
function openDetail(domain,id){
const x=findItem(domain,id);if(!x)return;
document.getElementById("page").style.display="none";
const d=document.getElementById("detailPage");d.classList.add("show");
if(domain==="org_units")d.innerHTML=detailOrg(x);
else if(domain==="regions")d.innerHTML=detailRegion(x);
else if(domain==="equipment")d.innerHTML=detailEquipment(x);
else if(domain==="key_nodes")d.innerHTML=detailNode(x);
else d.innerHTML=detailEventProject(x,domain);
location.hash=`#/detail/${domain}/${encodeURIComponent(id)}`;
window.scrollTo({top:0});
}
function back(){document.getElementById("detailPage").classList.remove("show");document.getElementById("page").style.display="block";location.hash="#/"+state.tab}
function F(label){var cfg=MANIFEST.字段显示;return !(cfg&&cfg[label]===false)}
function info(label,value){if(!F(label))return "";return `<div class="info-item"><label>${e(label)}</label><div>${value===undefined||value===null||value===""?'<span style="color:#999">未公开或未标注</span>':value}</div></div>`}
function listBlock(values){const v=a(values);return v.length?`<div class="text-list">${v.map(x=>`<div class="text-item">${e(x)}</div>`).join("")}</div>`:`<div class="empty" style="padding:20px">暂无独立条目</div>`}
function section(title,body){if(!F(title))return "";return `<section class="detail-section"><h3>${title}</h3>${body}</section>`}
function detailHeader(title,summary,tags){return `<span class="back-link" onclick="back()" style="color:var(--red);cursor:pointer;display:inline-block;margin-bottom:12px">← 返回上一页</span><div class="detail-hero"><h2>${e(title)}</h2><p>${e(summary)}</p><div class="detail-tags">${chips(tags,false,10)}</div></div>`}
function detailOrg(x){
const core=section("组织与单位概况",`<div class="info-grid">${info("记录类别",e(x.记录类别))}${info("体系",e(x.体系))}${info("架构层级",e(x.架构层级))}${info("组织或单位类型",e(x.单位类型))}${info("当前状态",statusChip(x.当前状态))}${info("可信度",e(x.可信度))}${info("行政上级",e(x.行政上级))}${info("军令或任务上级",e(x.军令或任务上级))}</div>`);
const tasks=section("公开职掌与任务",listBlock(x.公开任务));
const assoc=section("区域、装备与演训关联",`<div class="info-grid">${info("区域关联",chips(x.区域关联,true,12))}${info("装备类别",chips(x.装备类别,true,12))}${info("演训与事件",chips(x.演训与事件,true,12))}${info("适用范围",e(x.适用范围))}</div>`);
const childrenSec=section("直接下级机构或单位",x.下级机构.length?`<div class="mini-card-grid">${x.下级机构.map((n,i)=>`<div class="mini-card" ${x.下级机构编号[i]?`onclick="openDetail('org_units','${x.下级机构编号[i]}')" style="cursor:pointer"`:""}><b>${e(n)}</b><span style="font-size:11px;color:#888">点击查看档案</span></div>`).join("")}</div>`:`<div class="empty" style="padding:20px">未列出直接下级</div>`);
const relSec=section("组织关系",x.关系.length?`<div class="mini-card-grid">${x.关系.slice(0,16).map(r=>`<div class="mini-card"><b>${e(r.关系)}</b><div style="font-size:12px;line-height:1.65">${e(r.主体)} → ${e(r.客体)}</div><span style="font-size:11px;color:#888">${e(r.可信度)}</span></div>`).join("")}</div>`:`<div class="empty" style="padding:20px">暂无独立关系条目</div>`);
const history=section("历史沿革与说明",`<div class="text-item">${e(x.历史沿革)}</div>${x.说明?`<div class="text-item">${e(x.说明)}</div>`:""}`);
const gaps=section("资料缺口",`<div class="warning-box">${a(x.资料缺口).map(y=>`• ${e(y)}`).join("<br>")}</div>`);
const sources=section("来源与核实",`<div class="info-grid">${info("核实日期",e(x.核实日期))}${info("来源数量",String(a(x.来源).length))}</div><div style="margin-top:10px">${a(x.来源信息||x.来源).map(s=>`<div class="source-line">${e(s)}</div>`).join("")||'<div class="source-line">尚未列出独立来源编号</div>'}</div>`);
const safe=section("安全边界",`<div class="safe-box">${e(x.安全边界)}</div>`);
return detailHeader(x.名称,x.档案摘要,[x.记录类别,x.体系,x.当前状态])+`<div class="detail-grid"><div>${core}${tasks}${assoc}${childrenSec}${relSec}</div><aside>${history}${sources}${gaps}${safe}</aside></div>`;
}
function detailRegion(x){
const countyCards=x.县市子库.map(c=>`<div class="mini-card"><b>${e(c.name||c.county_name||c.名称||"县市子库")}</b><div style="font-size:12px;color:#777">${e(c.scope||c.沿岸范围||"沿岸县市档案")}</div></div>`).join("");
const segCards=x.海岸分段.map(s=>`<div class="mini-card"><b>${e(s.name||s.名称)}</b><div>${chips([s.coastal_type||s.海岸类型,s.所属区域],true,3)}</div><p style="font-size:11px;color:#777">${e(s.scope||s.空间范围||"")}</p></div>`).join("");
return detailHeader(x.名称,x.档案摘要,[x.编号,...a(x.海岸形态)])+
`<div class="detail-grid"><div>${section("区域基本信息",`<div class="info-grid">${info("空间范围",e(x.scope))}${info("县市数量",String(x.县市数量))}${info("海岸分段数量",String(x.分段数量))}${info("核实日期",e(x.last_verified||"未标注"))}${info("沿海县市",chips(x.沿海县市,true,15))}${info("支撑区域",chips(x.支撑区域,true,15))}</div>`)}${section("海岸形态",listBlock(x.海岸形态))}${section("海岸研究分段",`<div class="mini-card-grid">${segCards}</div>`)}</div><aside>${section("县市子库",`<div class="mini-card-grid" style="grid-template-columns:1fr">${countyCards}</div>`)}${section("资料来源",`<div>${a(x.来源信息||x.source_ids).map(s=>`<div class="source-line">${e(s)}</div>`).join("")||'<div class="source-line">待进一步补充</div>'}</div>`)}${section("研究边界",`<div class="safe-box">区域分段用于公开空间、治理和韧性研究,不等于军事防区、实际部署边界或行动分区。</div>`)}</aside></div>`;
}
function detailEquipment(x){
return detailHeader(x.名称,x.档案摘要,[x.类别中文,x.状态中文,...a(x.使用体系中文)])+
`<div class="detail-grid"><div>${section("装备概况",`<div class="info-grid">${info("装备类别",e(x.类别中文))}${info("使用体系",chips(x.使用体系中文,true,10))}${info("公开状态",statusChip(x.状态中文))}${info("可信度",e(x.可信度中文))}${info("别名",chips(x.aliases,true,10))}${info("核实日期",e(x.verified_at||"未标注"))}</div>`)}${section("公开作用",listBlock(x.公开作用))}${section("生命周期解释",`<div class="text-list"><div class="text-item">规划、预算、签约、交付、接装、训练、测评和形成能力属于不同阶段。</div><div class="text-item">本条目的当前状态为:${e(x.状态中文)}。</div><div class="text-item">装备价值需与感知、指挥、平台、保障和训练共同评估。</div></div>`)}</div><aside>${section("来源",a(x.来源信息||x.sources).map(s=>`<div class="source-line">${e(s)}</div>`).join("")||'<div class="source-line">待补</div>')}${section("备注",`<div class="text-item">${e(x.notes||"无额外公开说明。")}</div>`)}${section("资料边界",`<div class="safe-box">不记录或推断库存、精确部署、妥善率、射界、航线、战法和单位实际配赋。</div>`)}</aside></div>`;
}
function detailNode(x){
return detailHeader(x.名称,x.档案摘要,[x.类别中文,x.层级中文,x.状态中文])+
`<div class="detail-grid"><div>${section("节点概况",`<div class="info-grid">${info("节点类别",e(x.类别中文))}${info("节点层级",e(x.层级中文))}${info("所属区域",chips(x.区域中文,true,10))}${info("运行状态",statusChip(x.状态中文))}${info("主管或运营主体",e(x.主管运营))}${info("可信度",e(x.可信度中文))}</div>`)}${section("公共功能",listBlock(x.公共功能))}${section("上游依赖",listBlock(x.依赖类别))}${section("替代与备援",listBlock(x.替代备援))}</div><aside>${section("来源",a(x.来源信息||x.sources).map(s=>`<div class="source-line">${e(s)}</div>`).join("")||'<div class="source-line">待补</div>')}${section("资料说明",`<div class="text-item">${e(x.note||"无额外公开说明。")}</div>`)}${section("研究边界",`<div class="safe-box">节点用于公共功能、治理和韧性研究,不展示精确坐标、内部拓扑、实时容量、库存、脆弱点或攻击价值。</div>`)}</aside></div>`;
}
function detailEventProject(x,domain){
const isEvent=domain==="events";
return detailHeader(x.名称,x.档案摘要,[isEvent?x.类型中文:x.类别中文,x.状态中文])+
`<div class="detail-grid"><div>${section(isEvent?"事件信息":"项目信息",`<div class="info-grid">${info(isEvent?"事件类型":"项目类别",e(isEvent?x.类型中文:x.类别中文))}${info("状态",statusChip(x.状态中文))}${info("日期",e(x.日期显示||"不适用"))}${info("区域",chips(x.区域中文,true,12))}</div>`)}${section(isEvent?"主题与验证重点":"项目评估链条",isEvent?listBlock(x.topics):`<div class="text-list"><div class="text-item">规划与需求确认</div><div class="text-item">预算与采购</div><div class="text-item">生产、交付与接装</div><div class="text-item">训练、测评、保障与形成能力</div></div>`)}</div><aside>${section("来源",`<div class="source-line">${e(a(x.来源信息).join(";")||x.source||"待补")}</div>`)}${section("分析限制",`<div class="safe-box">${isEvent?"单次演习不能直接证明永久编制、完整战备或真实作战效果。":"项目存在不等于已经交付、接装或形成能力。"}</div>`)}</aside></div>`;
}
function openQueryBuilder(domainName){
const conf=QUERY_SCHEMA.查询域[domainName];if(!conf)return;
const opts=conf.字段.map(x=>`<option value="${e(x.字段)}">${e(x.显示名)}</option>`).join("");
const rows=(state.conditions.length?state.conditions:[{field:conf.字段[0].字段,op:"包含",value:""}]).map((c,i)=>queryRow(opts,c,i)).join("");
openModal(`<h2 style="margin-top:0">组合条件查询</h2><p style="color:#777;font-size:13px">使用中文字段构造条件,查询只作用于当前业务页面。</p><div id="queryRows">${rows}</div><button class="btn" onclick="addQueryRow('${domainName}')">增加条件</button> <button class="btn btn-red" onclick="applyQuery('${domainName}')">应用查询</button>`);
}
function queryRow(opts,c,i){return `<div class="query-row" data-query-row><select class="q-field">${opts.replace(`value="${c.field}"`,`value="${c.field}" selected`)}</select><select class="q-op"><option ${c.op==="包含"?"selected":""}>包含</option><option ${c.op==="等于"?"selected":""}>等于</option><option ${c.op==="属于"?"selected":""}>属于</option></select><input class="q-value" value="${e(c.value)}" placeholder="输入查询值"><button class="btn" onclick="this.parentElement.remove()">×</button></div>`}
function addQueryRow(domainName){const conf=QUERY_SCHEMA.查询域[domainName];const opts=conf.字段.map(x=>`<option value="${e(x.字段)}">${e(x.显示名)}</option>`).join("");document.getElementById("queryRows").insertAdjacentHTML("beforeend",queryRow(opts,{field:conf.字段[0].字段,op:"包含",value:""},99))}
function applyQuery(){state.conditions=[...document.querySelectorAll("[data-query-row]")].map(r=>({field:r.querySelector(".q-field").value,op:r.querySelector(".q-op").value,value:r.querySelector(".q-value").value})).filter(x=>x.value);state.page=1;closeModal();render()}
function openModal(html){document.getElementById("modal").innerHTML=html;document.getElementById("modalOverlay").classList.add("show")}
function closeModal(){document.getElementById("modalOverlay").classList.remove("show")}
function closeDrawer(){document.getElementById("drawerOverlay").classList.remove("show")}
document.getElementById("modalOverlay").onclick=x=>{if(x.target.id==="modalOverlay")closeModal()};
document.getElementById("drawerOverlay").onclick=x=>{if(x.target.id==="drawerOverlay")closeDrawer()};
/* ── 页面 JSON 编辑器 ──────────────────────────────────────────────
* 模块 = DATA 顶层键(Tab 标签取 MANIFEST.页面 的中文名)+「系统设置」编辑 MANIFEST。
* 应用 → 原地替换 DATA/MANIFEST → 重置交互状态 → render() 整体重渲染;
* 修改按数据指纹存 localStorage(沙箱 iframe 禁存储时 try/catch 静默降级,仅会话内有效),
* 不回写服务器——服务端持久化走模板管理页「编辑数据」。 */
(function(){
"use strict";
function clone(v){return JSON.parse(JSON.stringify(v))}
function draftsToData(d){var o={};Object.keys(d||{}).forEach(function(k){if(k!=="__manifest__")o[k]=d[k]});return o}
function draftsFrom(d,m){var o={};Object.keys(d||{}).forEach(function(k){o[k]=d[k]});o.__manifest__=m;return o}
function replaceInPlace(target,src){Object.keys(target).forEach(function(k){delete target[k]});Object.keys(src).forEach(function(k){target[k]=src[k]})}
var initialData=clone(DATA),initialManifest=clone(MANIFEST);
var initialModules=Object.keys(DATA).concat(["__manifest__"]);
// 本地缓存键按初始数据指纹生成:模板/产物内容变了,旧缓存自然失效。
var fingerprint=(function(){var h=2166136261,s=JSON.stringify(initialData)+"|"+JSON.stringify(initialManifest);for(var i=0;i<s.length;i++){h^=s.charCodeAt(i);h=Math.imul(h,16777619)}return (h>>>0).toString(36)})();
var storageKey="structured-page-data-v1:"+fingerprint;
function readLS(k){try{return window.localStorage?window.localStorage.getItem(k):null}catch(x){return null}}
function writeLS(k,v){try{if(window.localStorage)window.localStorage.setItem(k,v);return true}catch(x){return false}}
function removeLS(k){try{if(window.localStorage)window.localStorage.removeItem(k)}catch(x){}}
// 启动恢复:有合法缓存则应用(本段在首帧 render() 之前执行)。
(function(){
var cached=readLS(storageKey);if(!cached)return;
try{
var parsed=JSON.parse(cached);
if(parsed&&typeof parsed==="object"&&parsed.data&&parsed.manifest&&initialModules.every(function(k){
return k==="__manifest__"||typeof parsed.data[k]==="object"&&parsed.data[k]&&!Array.isArray(parsed.data[k]);
})){
replaceInPlace(DATA,parsed.data);replaceInPlace(MANIFEST,parsed.manifest)
}
}catch(x){/* 缓存损坏则忽略,沿用模板默认数据 */}
})();
var labels={};a(MANIFEST.页面).forEach(function(p){if(p&&p.编号)labels[p.编号]=p.名称||p.编号});
var modules=Object.keys(DATA).concat(["__manifest__"]);
var active=modules[0]||"__manifest__";
var drafts=draftsFrom(clone(DATA),clone(MANIFEST));
function moduleTitle(key){return key==="__manifest__"?"系统设置(MANIFEST)":(labels[key]||key)}
function validDrafts(){return modules.every(function(k){var v=drafts[k];return v&&typeof v==="object"&&!Array.isArray(v)})}
var overlay=document.getElementById("editorOverlay");
if(!overlay)return; // 骨架缺编辑器标记(被手工裁掉)时安全退出
var tabsEl=document.getElementById("editorTabs");
var editor=document.getElementById("jsonEditor");
var statusEl=document.getElementById("jsonStatus");
var titleEl=document.getElementById("editorModuleTitle");
function setStatus(ok,msg){statusEl.textContent=msg;statusEl.className="json-status "+(ok?"valid":"invalid")}
function readEditor(){
try{
var parsed=JSON.parse(editor.value);
if(!parsed||typeof parsed!=="object"||Array.isArray(parsed))throw new Error("模块必须是 JSON 对象");
setStatus(true,"JSON 有效");return parsed
}catch(x){setStatus(false,"JSON 无效:"+x.message);return null}
}
function saveActiveDraft(){var parsed=readEditor();if(!parsed)return false;drafts[active]=parsed;return true}
function loadEditor(){titleEl.textContent=moduleTitle(active);editor.value=JSON.stringify(drafts[active],null,2);setStatus(true,"JSON 有效")}
function renderTabs(){
tabsEl.innerHTML="";
modules.forEach(function(key){
var b=document.createElement("button");b.type="button";
b.className="editor-tab"+(key===active?" active":"");
b.innerHTML="<b>"+e(moduleTitle(key))+"</b><small>"+(key==="__manifest__"?"MANIFEST":key)+"</small>";
b.onclick=function(){if(key===active||!saveActiveDraft())return;active=key;renderTabs();loadEditor()};
tabsEl.appendChild(b)
})
}
function closeEditor(){overlay.classList.remove("show")}
function applyToPage(){
if(!saveActiveDraft()||!validDrafts()){setStatus(false,"存在无效模块,请先修正");return}
replaceInPlace(DATA,draftsToData(drafts));
replaceInPlace(MANIFEST,drafts.__manifest__);
// 重置交互状态后整体重渲染(tab 回到第一个页面)。
state.tab=(MANIFEST.页面&&MANIFEST.页面[0]&&MANIFEST.页面[0].编号)||"overview";
state.mode="chart";state.chart="national_defense";state.q="";state.filters={};state.conditions=[];state.page=1;
closeEditor();render();syncHeader();
writeLS(storageKey,JSON.stringify({data:DATA,manifest:MANIFEST}))
}
function legacyCopy(text){var t=document.createElement("textarea");t.value=text;document.body.appendChild(t);t.select();try{document.execCommand("copy")}catch(x){}t.remove()}
function copyText(text,done){
if(navigator.clipboard&&navigator.clipboard.writeText){navigator.clipboard.writeText(text).then(done,function(){legacyCopy(text);done()})}
else{legacyCopy(text);done()}
}
document.getElementById("openEditor").onclick=function(){
drafts=draftsFrom(clone(DATA),clone(MANIFEST));
active=modules[0]||"__manifest__";
renderTabs();loadEditor();
overlay.classList.add("show");
setTimeout(function(){editor.focus()},40)
};
document.getElementById("closeEditor").onclick=closeEditor;
overlay.onclick=function(ev){if(ev.target===overlay)closeEditor()};
document.addEventListener("keydown",function(ev){if(ev.key==="Escape"&&overlay.classList.contains("show"))closeEditor()});
document.getElementById("applyJson").onclick=applyToPage;
document.getElementById("resetJson").onclick=function(){
drafts=draftsFrom(clone(initialData),clone(initialManifest));
active=modules[0]||"__manifest__";
removeLS(storageKey);
renderTabs();loadEditor();
setStatus(true,"已恢复默认数据,点击「应用到页面」生效")
};
document.getElementById("copyJson").onclick=function(){
if(!saveActiveDraft())return;
copyText(JSON.stringify({data:draftsToData(drafts),manifest:drafts.__manifest__},null,2),function(){})
};
document.getElementById("downloadJson").onclick=function(){
if(!saveActiveDraft())return;
var blob=new Blob([JSON.stringify({data:draftsToData(drafts),manifest:drafts.__manifest__},null,2)],{type:"application/json;charset=utf-8"});
var link=document.createElement("a");link.href=URL.createObjectURL(blob);link.download="page-data.json";link.click();
setTimeout(function(){URL.revokeObjectURL(link.href)},1000)
};
})();
function syncHeader(){
var sys=MANIFEST.系统||{};
if(sys.名称){document.title=String(sys.名称);var h1=document.querySelector(".title h1");if(h1)h1.textContent=String(sys.名称)}
var hs=document.querySelector(".header-state");
if(hs){var ver=sys.知识库版本,upd=sys.更新时间;if(ver||upd)hs.innerHTML="知识库版本 "+e(ver||"")+"<br>更新日期 "+e(upd||"")}
}
syncHeader();
const hash=location.hash.match(/^#\/([^/]+)/);if(hash&&MANIFEST.页面.some(x=>x.编号===hash[1]))state.tab=hash[1];render();
@@ -0,0 +1,98 @@
<!doctype html>
<html lang="zh-CN">
<head>
<meta charset="utf-8">
<meta name="viewport" content="width=device-width,initial-scale=1">
<title>台湾滨海防卫知识数据展示系统</title>
<style>
:root{
--red:#c8102e;--red2:#8f1024;--light-red:#fff1f3;--soft-red:#fde7eb;
--bg:#f5f5f6;--card:#fff;--text:#262626;--muted:#737373;--line:#e5e5e5;
--green:#168a4a;--orange:#c56a00;--shadow:0 8px 24px rgba(74,12,24,.08)
}
*{box-sizing:border-box}html{scroll-behavior:smooth}body{margin:0;background:var(--bg);color:var(--text);font-family:"PingFang SC","Microsoft YaHei",Arial,sans-serif}
button,input,select{font:inherit}.header{position:sticky;top:0;z-index:30;background:#fff;border-bottom:1px solid var(--line);box-shadow:0 3px 12px rgba(0,0,0,.04)}
.header-top{height:70px;padding:0 28px;display:flex;align-items:center;gap:24px}.logo{width:42px;height:42px;border-radius:12px;background:linear-gradient(145deg,var(--red),var(--red2));display:grid;place-items:center;color:#fff;font-weight:800}
.title{flex:1}.title h1{font-size:19px;margin:0 0 5px}.title p{margin:0;font-size:12px;color:var(--muted)}.header-state{text-align:right;font-size:12px;color:var(--muted)}
.tabs{display:flex;padding:0 24px;gap:4px;overflow:auto}.tab{border:0;background:transparent;padding:13px 18px;color:#666;cursor:pointer;border-bottom:3px solid transparent;white-space:nowrap}.tab.active{color:var(--red);font-weight:700;border-bottom-color:var(--red);background:linear-gradient(to top,var(--light-red),transparent)}
.main{padding:24px 28px 48px}.hero{background:linear-gradient(135deg,#fff,#fff5f6);border:1px solid #f2d4d9;border-radius:20px;padding:24px;display:flex;justify-content:space-between;align-items:center;gap:20px;margin-bottom:18px;box-shadow:var(--shadow)}
.hero h2{margin:0 0 8px;font-size:26px}.hero p{margin:0;color:var(--muted);line-height:1.7}.hero-mark{width:90px;height:90px;border-radius:50%;background:radial-gradient(circle,#fff 0 30%,#fbd5dc 31% 55%,var(--red) 56%);opacity:.9}
.btn{border:1px solid #d8d8d8;background:#fff;color:#333;border-radius:9px;padding:8px 13px;cursor:pointer}.btn:hover{border-color:var(--red);color:var(--red)}.btn-red{background:var(--red);border-color:var(--red);color:#fff}.btn-red:hover{background:var(--red2);color:#fff}.btn-soft{background:var(--light-red);color:var(--red);border-color:#f0bec8}
.metrics{display:grid;grid-template-columns:repeat(3,1fr);gap:14px;margin-bottom:18px}.metric{background:#fff;border:1px solid var(--line);border-radius:16px;padding:17px;box-shadow:var(--shadow);position:relative;overflow:hidden}.metric:after{content:"";position:absolute;right:-20px;top:-30px;width:90px;height:90px;border-radius:50%;background:var(--light-red)}.metric-label{font-size:13px;color:var(--muted)}.metric-value{font-size:30px;font-weight:800;color:var(--red);margin-top:8px}.metric-unit{font-size:12px;margin-left:4px}.metric-note{font-size:12px;color:#888;margin-top:6px}
.grid2{display:grid;grid-template-columns:1fr 1fr;gap:16px}.panel{background:#fff;border:1px solid var(--line);border-radius:17px;padding:18px;box-shadow:var(--shadow)}.panel-title{font-weight:800;margin-bottom:14px;display:flex;align-items:center;justify-content:space-between}.panel-title:before{content:"";width:5px;height:18px;background:var(--red);border-radius:5px;margin-right:9px}.panel-title span:first-child{display:flex;align-items:center}
.bar-row{display:grid;grid-template-columns:150px 1fr 38px;gap:10px;align-items:center;font-size:12px;margin:10px 0}.bar{height:9px;background:#f1f1f1;border-radius:20px;overflow:hidden}.bar i{display:block;height:100%;background:linear-gradient(90deg,var(--red),#ed6b7e);border-radius:20px}
.entry-grid,.card-grid{display:grid;grid-template-columns:repeat(3,1fr);gap:14px}.entry-card,.data-card{background:#fff;border:1px solid var(--line);border-radius:16px;padding:17px;box-shadow:var(--shadow);cursor:pointer;transition:.18s}.entry-card:hover,.data-card:hover{transform:translateY(-2px);border-color:#e0a0ab}.entry-card b,.data-card h3{display:block;margin:0 0 8px}.entry-num{font-size:25px;color:var(--red);font-weight:800}.entry-card p,.data-card p{font-size:12px;color:var(--muted);line-height:1.65;margin:8px 0 0}
.toolbar{background:#fff;border:1px solid var(--line);border-radius:14px;padding:12px;display:flex;gap:9px;align-items:center;flex-wrap:wrap;margin-bottom:16px;box-shadow:var(--shadow)}.toolbar input,.toolbar select{height:37px;border:1px solid #ddd;border-radius:8px;background:#fff;padding:0 10px;color:#333}.toolbar input{flex:1;min-width:250px}.toolbar-count{margin-left:auto;color:var(--muted);font-size:12px}
.chip{display:inline-flex;align-items:center;border-radius:999px;padding:4px 9px;background:#f3f3f3;color:#555;font-size:11px;margin:2px}.chip-red{background:var(--light-red);color:var(--red)}.chip-green{background:#edf9f2;color:var(--green)}.chip-orange{background:#fff6e8;color:var(--orange)}
.region-grid{display:grid;grid-template-columns:repeat(3,1fr);gap:15px}.region-card{background:#fff;border:1px solid var(--line);border-radius:18px;padding:18px;box-shadow:var(--shadow);cursor:pointer;position:relative;overflow:hidden}.region-card:before{content:"";position:absolute;left:0;top:0;bottom:0;width:5px;background:var(--red)}.region-card h3{margin:0 0 8px;font-size:18px}.region-card p{font-size:12px;color:var(--muted);line-height:1.7}.region-stats{display:flex;gap:18px;margin-top:13px;border-top:1px solid #f0f0f0;padding-top:12px}.region-stats b{color:var(--red);font-size:18px}
.segmented{display:flex;gap:5px;background:#f0f0f0;padding:4px;border-radius:11px;width:max-content;margin-bottom:15px}.seg-btn{border:0;background:transparent;padding:8px 14px;border-radius:8px;color:#666;cursor:pointer}.seg-btn.active{background:#fff;color:var(--red);font-weight:700;box-shadow:0 2px 7px rgba(0,0,0,.08)}
.chart-toolbar{display:flex;gap:8px;flex-wrap:wrap;margin-bottom:16px}.chart-view{padding:9px 14px;border:1px solid #e1c3c9;background:#fff7f8;color:#8c2335;border-radius:9px;cursor:pointer}.chart-view.active{background:var(--red);color:#fff;border-color:var(--red)}
.org-chart-wrap{overflow:auto;background:#fff;border:1px solid var(--line);border-radius:18px;padding:28px;box-shadow:var(--shadow);min-height:420px}
.org-chart{display:flex;justify-content:center;min-width:max-content}.org-chart ul{padding-top:24px;position:relative;display:flex;justify-content:center;margin:0;padding-left:0}.org-chart li{list-style:none;text-align:center;position:relative;padding:24px 8px 0}.org-chart li:before,.org-chart li:after{content:"";position:absolute;top:0;right:50%;border-top:1px solid #c7a8ae;width:50%;height:24px}.org-chart li:after{right:auto;left:50%;border-left:1px solid #c7a8ae}.org-chart li:only-child:after,.org-chart li:only-child:before{display:none}.org-chart li:only-child{padding-top:0}.org-chart li:first-child:before,.org-chart li:last-child:after{border:0}.org-chart li:last-child:before{border-right:1px solid #c7a8ae;border-radius:0 6px 0 0}.org-chart li:first-child:after{border-radius:6px 0 0 0}.org-chart ul ul:before{content:"";position:absolute;top:0;left:50%;border-left:1px solid #c7a8ae;width:0;height:24px}
.org-node{width:168px;min-height:80px;background:#fff;border:1px solid #e3c1c7;border-top:4px solid var(--red);border-radius:12px;padding:10px;display:inline-block;box-shadow:0 5px 14px rgba(96,12,28,.08);cursor:pointer}.org-node:hover{background:#fff6f7;border-color:var(--red)}.org-node b{font-size:13px;display:block;line-height:1.45}.org-node small{font-size:10px;color:var(--muted);display:block;margin-top:5px}.org-node .node-kind{font-size:10px;color:var(--red);margin-top:5px}
.summary-strip{display:grid;grid-template-columns:repeat(4,1fr);gap:12px;margin:15px 0}.summary-card{background:#fff;border:1px solid var(--line);border-radius:13px;padding:14px}.summary-card b{display:block;color:var(--red);font-size:21px}.summary-card span{font-size:12px;color:var(--muted)}
.data-card{display:flex;flex-direction:column;min-height:205px}.card-top{display:flex;justify-content:space-between;gap:10px}.card-type{font-size:11px;color:var(--red);background:var(--light-red);padding:4px 8px;border-radius:999px;height:max-content}.card-sub{font-size:12px;color:#777;margin-bottom:10px}.card-roles{display:grid;gap:6px;margin-top:8px}.role-line{font-size:12px;background:#fafafa;border-left:3px solid #e7a1ad;padding:7px 9px}.card-footer{margin-top:auto;padding-top:12px;border-top:1px solid #eee;display:flex;justify-content:space-between;color:#888;font-size:11px}
.category-grid{display:grid;grid-template-columns:repeat(5,1fr);gap:10px;margin-bottom:16px}.category-card{background:#fff;border:1px solid var(--line);border-radius:13px;padding:13px;cursor:pointer}.category-card:hover{border-color:var(--red)}.category-card b{color:var(--red);font-size:21px;display:block}.category-card span{font-size:11px;color:#666}
.timeline{position:relative;padding-left:26px}.timeline:before{content:"";position:absolute;left:7px;top:4px;bottom:4px;width:2px;background:#efc5cc}.time-card{position:relative;background:#fff;border:1px solid var(--line);border-radius:14px;padding:16px;margin-bottom:14px;box-shadow:var(--shadow);cursor:pointer}.time-card:before{content:"";position:absolute;left:-25px;top:19px;width:12px;height:12px;border:3px solid var(--red);background:#fff;border-radius:50%}.time-date{color:var(--red);font-size:12px;font-weight:700;margin-bottom:5px}
.pagination{display:flex;justify-content:center;align-items:center;gap:9px;margin-top:18px}.page-no{color:#777;font-size:12px}
.overlay{position:fixed;inset:0;background:rgba(36,8,14,.42);z-index:50;display:none}.overlay.show{display:block}.drawer{position:absolute;right:0;top:0;width:min(560px,94vw);height:100%;background:#fff;padding:24px;overflow:auto;box-shadow:-12px 0 35px rgba(0,0,0,.16)}.modal{position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);width:min(840px,92vw);max-height:88vh;overflow:auto;background:#fff;border-radius:18px;padding:24px}.close{float:right}
.detail-page{display:none}.detail-page.show{display:block}.detail-hero{background:linear-gradient(135deg,var(--red),var(--red2));color:#fff;border-radius:20px;padding:25px;margin-bottom:16px;box-shadow:var(--shadow)}.detail-hero h2{margin:0 0 10px;font-size:26px}.detail-hero p{margin:0;line-height:1.7;color:#ffe8ed}.detail-tags{margin-top:13px}.detail-tags .chip{background:rgba(255,255,255,.16);color:#fff}
.detail-grid{display:grid;grid-template-columns:2fr 1fr;gap:16px}.detail-section{background:#fff;border:1px solid var(--line);border-radius:16px;padding:18px;margin-bottom:16px;box-shadow:var(--shadow)}.detail-section h3{margin:0 0 14px;font-size:16px;display:flex;align-items:center}.detail-section h3:before{content:"";width:4px;height:17px;background:var(--red);border-radius:5px;margin-right:8px}.info-grid{display:grid;grid-template-columns:repeat(2,1fr);gap:10px}.info-item{background:#fafafa;border-radius:10px;padding:11px}.info-item label{display:block;font-size:11px;color:#888;margin-bottom:5px}.info-item div{font-size:13px;line-height:1.55}.text-list{display:grid;gap:9px}.text-item{padding:10px 12px;border-left:4px solid #e5a6b1;background:#fff8f9;border-radius:7px;font-size:13px;line-height:1.6}
.mini-card-grid{display:grid;grid-template-columns:repeat(2,1fr);gap:10px}.mini-card{border:1px solid #eee;border-radius:11px;padding:12px;background:#fff}.mini-card b{display:block;margin-bottom:6px}.source-line{padding:9px 0;border-bottom:1px dashed #ddd;font-size:12px}.warning-box{background:#fff7e8;border:1px solid #f1d29e;border-radius:11px;padding:13px;color:#7a4d00;font-size:12px;line-height:1.65}.safe-box{background:#f7f7f7;border:1px solid #ddd;border-radius:11px;padding:13px;color:#555;font-size:12px;line-height:1.65}
.query-row{display:grid;grid-template-columns:1fr 120px 1fr 42px;gap:8px;margin-bottom:8px}.query-row select,.query-row input{height:37px;border:1px solid #ddd;border-radius:8px;padding:0 9px}.empty{text-align:center;padding:50px;color:#888}
@media(max-width:1150px){.entry-grid,.card-grid,.region-grid{grid-template-columns:repeat(2,1fr)}.category-grid{grid-template-columns:repeat(3,1fr)}.detail-grid{grid-template-columns:1fr}.metrics{grid-template-columns:repeat(2,1fr)}}
@media(max-width:720px){.header-top{padding:10px 14px;height:auto}.header-state{display:none}.main{padding:14px}.hero-mark{display:none}.hero h2{font-size:21px}.metrics,.grid2,.entry-grid,.card-grid,.region-grid,.summary-strip,.category-grid,.info-grid,.mini-card-grid{grid-template-columns:1fr}.toolbar input{min-width:100%}.query-row{grid-template-columns:1fr}.org-chart-wrap{padding:15px}.org-node{width:145px}}
/* ── 页面 JSON 编辑器 ── */
.editor-fab{position:fixed;right:18px;bottom:26px;z-index:40;background:var(--red);color:#fff;border:0;border-radius:50%;width:46px;height:46px;display:grid;place-items:center;cursor:pointer;box-shadow:0 6px 18px rgba(143,16,36,.32)}.editor-fab:hover{background:var(--red2);transform:rotate(30deg)}.editor-fab svg{width:22px;height:22px;display:block}
.editor-overlay{z-index:60}
.editor-modal{position:absolute;left:50%;top:50%;transform:translate(-50%,-50%);width:min(1080px,94vw);height:min(680px,88vh);background:#fff;border-radius:18px;display:flex;flex-direction:column;overflow:hidden;box-shadow:0 24px 60px rgba(36,8,14,.3)}
.editor-head{display:flex;align-items:center;gap:12px;padding:14px 18px;border-bottom:1px solid var(--line)}.editor-head h2{margin:0;font-size:16px;flex:1}.editor-head .editor-note{font-size:12px;color:var(--muted);margin-right:8px}
.editor-body{display:flex;flex:1;min-height:0}
.editor-tabs{width:210px;border-right:1px solid var(--line);overflow:auto;padding:10px 8px;display:flex;flex-direction:column;gap:4px}
.editor-tab{border:0;background:transparent;text-align:left;padding:9px 11px;border-radius:9px;cursor:pointer;color:#555}.editor-tab b{display:block;font-size:13px}.editor-tab small{font-size:11px;color:#999}.editor-tab:hover{background:var(--light-red)}.editor-tab.active{background:var(--light-red);color:var(--red)}
.editor-pane{flex:1;display:flex;flex-direction:column;min-width:0;padding:14px 16px;gap:10px}
.editor-title-row{display:flex;align-items:center;justify-content:space-between}.editor-title-row b{font-size:14px}
.json-status{font-size:12px;padding:3px 10px;border-radius:999px}.json-status.valid{background:#edf9f2;color:var(--green)}.json-status.invalid{background:var(--light-red);color:var(--red)}
.json-editor{flex:1;width:100%;resize:none;border:1px solid var(--line);border-radius:12px;padding:13px;font:13px/1.6 ui-monospace,Consolas,"Courier New",monospace;color:#333;background:#fafafa;outline:0;tab-size:2}.json-editor:focus{border-color:var(--red);box-shadow:0 0 0 3px rgba(200,16,46,.1)}
.editor-actions{display:flex;gap:8px;flex-wrap:wrap}
.editor-hint{margin:0;font-size:11px;color:#999}
@media(max-width:720px){.editor-modal{width:96vw;height:92vh}.editor-body{flex-direction:column}.editor-tabs{width:auto;flex-direction:row;overflow-x:auto;border-right:0;border-bottom:1px solid var(--line)}.editor-tab{white-space:nowrap}}
</style>
</head>
<body>
<header class="header">
<div class="header-top">
<div class="logo">防</div>
<div class="title"><h1>台湾滨海防卫知识数据展示系统</h1><p>红白业务版 · 组织架构与单位档案已合并</p></div>
<div class="header-state">知识库版本 2.0<br>更新日期 2026-06-23</div>
</div>
<nav class="tabs" id="tabs"></nav>
</header>
<main class="main">
<section id="page"></section>
<section id="detailPage" class="detail-page"></section>
</main>
<div id="drawerOverlay" class="overlay"><aside class="drawer"><button class="btn close" onclick="closeDrawer()">关闭</button><div id="drawer"></div></aside></div>
<div id="modalOverlay" class="overlay"><div class="modal"><button class="btn close" onclick="closeModal()">关闭</button><div id="modal"></div></div></div>
<button type="button" id="openEditor" class="editor-fab" aria-label="JSON 编辑器" title="页面 JSON 编辑器"><svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="2" stroke-linecap="round" stroke-linejoin="round" aria-hidden="true"><path d="M12.22 2h-.44a2 2 0 0 0-2 2v.18a2 2 0 0 1-1 1.73l-.43.25a2 2 0 0 1-2 0l-.15-.08a2 2 0 0 0-2.73.73l-.22.38a2 2 0 0 0 .73 2.73l.15.1a2 2 0 0 1 1 1.72v.51a2 2 0 0 1-1 1.74l-.15.09a2 2 0 0 0-.73 2.73l.22.38a2 2 0 0 0 2.73.73l.15-.08a2 2 0 0 1 2 0l.43.25a2 2 0 0 1 1 1.73V20a2 2 0 0 0 2 2h.44a2 2 0 0 0 2-2v-.18a2 2 0 0 1 1-1.73l.43-.25a2 2 0 0 1 2 0l.15.08a2 2 0 0 0 2.73-.73l.22-.39a2 2 0 0 0-.73-2.73l-.15-.08a2 2 0 0 1-1-1.74v-.5a2 2 0 0 1 1-1.74l.15-.09a2 2 0 0 0 .73-2.73l-.22-.38a2 2 0 0 0-2.73-.73l-.15.08a2 2 0 0 1-2 0l-.43-.25a2 2 0 0 1-1-1.73V4a2 2 0 0 0-2-2z"/><circle cx="12" cy="12" r="3"/></svg></button>
<div id="editorOverlay" class="overlay editor-overlay">
<div class="editor-modal">
<header class="editor-head"><h2>页面 JSON 编辑器</h2><span class="editor-note">按模块编辑,应用后即时重渲染;修改保存在浏览器本地,不回写服务器</span><button type="button" class="btn" id="closeEditor">关闭</button></header>
<div class="editor-body">
<nav id="editorTabs" class="editor-tabs"></nav>
<div class="editor-pane">
<div class="editor-title-row"><b id="editorModuleTitle"></b><span id="jsonStatus" class="json-status valid">JSON 有效</span></div>
<textarea id="jsonEditor" class="json-editor" spellcheck="false" aria-label="当前模块 JSON"></textarea>
<div class="editor-actions"><button type="button" class="btn btn-red" id="applyJson">应用到页面</button><button type="button" class="btn" id="resetJson">恢复默认数据</button><button type="button" class="btn" id="copyJson">复制完整 JSON</button><button type="button" class="btn" id="downloadJson">下载 JSON</button></div>
<p class="editor-hint">模块 = 页面数据(DATA)的顶层键,另附「系统设置」编辑 MANIFEST;沙箱预览(iframe)无法使用本地缓存时,修改仅当次会话有效。</p>
</div>
</div>
</div>
</div>
<script type="application/json" id="page-data">__PAGE_DATA__</script>
<script type="application/json" id="page-manifest">__PAGE_MANIFEST__</script>
<script>__PAGE_RUNTIME__</script>
</body>
</html>
@@ -314,43 +314,41 @@ def _resolve_skills_path(path: str) -> str:
return _join_path_preserving_style(skills_host, relative)
def _custom_skill_name_from_path(path: str) -> str | None:
"""从虚拟技能路径里解析出 custom 技能名,用于"被使用"埋点。
只识别 ``{skills_container}/custom/{name}/...`` 形式 —— public 技能不参与
策展,给它们埋点只会往 ``.usage.json`` 写无用条目。读技能目录下任意文件
(SKILL.md 或 references/templates/scripts 支持文件)都算一次该技能的使用。
解析不出技能名时返回 None。
"""
skills_container = _get_skills_container_path()
if not (path == skills_container or path.startswith(f"{skills_container}/")):
return None
relative = path[len(skills_container) :].lstrip("/")
parts = [segment for segment in relative.split("/") if segment]
if len(parts) >= 2 and parts[0] == "custom":
return parts[1]
return None
def _record_skill_read(virtual_path: str) -> None:
"""技能文件被 ``read_file`` 读取时记一次 use —— 技能"被使用"的真实信号。
技能正文不进 system prompt(prompt 里只有 name/description/location),Agent
按 Progressive Loading 用 ``read_file`` 加载 SKILL.md 才算真正用到该技能。
curator 的年龄流转据此判断闲置,没有这个埋点会把每天都在用的技能误判为陈旧。
best-effort:埋点失败绝不影响 ``read_file`` 本身。
"""
def _record_skill_paths(
virtual_paths: list[str],
runtime: ToolRuntime[ContextT, ThreadState] | None,
) -> None:
"""Record public/custom skills from real tool paths, independent of prose."""
try:
name = _custom_skill_name_from_path(virtual_path)
if name is None:
return
from deerflow.skills.usage import bump_use
from deerflow.sandbox.skill_view import skill_names_for_paths
from deerflow.skills.usage import bump_use, runtime_use_event_key
bump_use(name)
event_key = runtime_use_event_key(runtime)
for name in skill_names_for_paths(
virtual_paths,
container_path=_get_skills_container_path(),
):
bump_use(name, event_key=event_key)
except Exception:
pass
def _record_skill_read(
virtual_path: str,
runtime: ToolRuntime[ContextT, ThreadState] | None = None,
) -> None:
"""Count a successful skill file read as a logical skill invocation."""
_record_skill_paths([virtual_path], runtime)
def _record_skill_command(
command: str,
runtime: ToolRuntime[ContextT, ThreadState] | None = None,
) -> None:
"""Count skills whose scripts are executed directly by ``bash``."""
_record_skill_paths(_skill_paths_in_text(command), runtime)
def _is_acp_workspace_path(path: str) -> bool:
"""Check if a path is under the ACP workspace virtual path."""
return path == _ACP_WORKSPACE_VIRTUAL_PATH or path.startswith(f"{_ACP_WORKSPACE_VIRTUAL_PATH}/")
@@ -1445,6 +1443,7 @@ def bash_tool(runtime: ToolRuntime[ContextT, ThreadState], description: str, com
command: The bash command to execute. Always use absolute paths for files and directories.
"""
try:
requested_command = command
_prepare_command_skill_capability(command)
_validate_enabled_skill_paths_in_command(command)
sandbox = ensure_sandbox_initialized(runtime)
@@ -1457,6 +1456,7 @@ def bash_tool(runtime: ToolRuntime[ContextT, ThreadState], description: str, com
command = replace_virtual_paths_in_command(command, thread_data)
command = _apply_cwd_prefix(command, thread_data)
output = sandbox.execute_command(command)
_record_skill_command(requested_command, runtime)
try:
from deerflow.config.app_config import get_app_config
@@ -1473,7 +1473,9 @@ def bash_tool(runtime: ToolRuntime[ContextT, ThreadState], description: str, com
max_chars = sandbox_cfg.bash_output_max_chars if sandbox_cfg else 20000
except Exception:
max_chars = 20000
return _truncate_bash_output(sandbox.execute_command(command), max_chars)
output = sandbox.execute_command(command)
_record_skill_command(requested_command, runtime)
return _truncate_bash_output(output, max_chars)
except SandboxError as e:
return f"Error: {e}"
except PermissionError as e:
@@ -1751,7 +1753,7 @@ def read_file_tool(
max_result_chars=max_chars,
hard_max_result_chars=hard_max,
)
_record_skill_read(requested_path)
_record_skill_read(requested_path, runtime)
return inspected["rendered"]
except OSError:
pass
@@ -1767,7 +1769,7 @@ def read_file_tool(
)
# 读成功即记一次技能使用 —— requested_path 仍是虚拟路径(本地/容器沙箱都一样),
# 非技能路径会被 _record_skill_read 自行忽略。
_record_skill_read(requested_path)
_record_skill_read(requested_path, runtime)
if not content and not truncated:
return "(empty)"
if truncated:
@@ -7,6 +7,7 @@ import logging
import os
import tempfile
import threading
from collections import OrderedDict
from datetime import UTC, datetime
from pathlib import Path
@@ -19,6 +20,14 @@ _USAGE_FILENAME = ".usage.json"
# 单进程跑,故进程内锁即可保证状态流转不丢。
_usage_lock = threading.Lock()
# One user run can first load SKILL.md and then execute several helper scripts.
# Those are implementation details of one logical skill invocation, so retain a
# small process-local LRU keyed by (run, skill) and increment the public counter
# only once. A run stays on one worker; persistence across restarts is neither
# needed nor desirable here.
_MAX_RECENT_USE_EVENTS = 8192
_recent_use_events: OrderedDict[tuple[str, str], None] = OrderedDict()
STATE_ACTIVE = "active"
STATE_STALE = "stale"
STATE_ARCHIVED = "archived"
@@ -121,8 +130,110 @@ def bump_view(name: str) -> None:
_update_entry(name, lambda e: {"view_count": e.get("view_count", 0) + 1, "last_viewed_at": _now_iso()})
def bump_use(name: str) -> None:
_update_entry(name, lambda e: {"use_count": e.get("use_count", 0) + 1, "last_used_at": _now_iso()})
async def _increment_use_projection(name: str, use_count: int, used_at: datetime) -> None:
"""Keep the MySQL skill-list projection current without importing ``app``."""
try:
from sqlalchemy import case, update
from deerflow.persistence.engine import get_session_factory
from deerflow.persistence.skills.model import SkillRow
session_factory = get_session_factory()
if session_factory is None:
return
async with session_factory() as session:
await session.execute(
update(SkillRow)
.where(SkillRow.name == name)
.values(
# Fire-and-forget writes may finish out of order. Never let
# an older absolute sidecar count overwrite a newer value.
use_count=case((SkillRow.use_count < use_count, use_count), else_=SkillRow.use_count),
last_activity_at=case(
(SkillRow.last_activity_at.is_(None), used_at),
(SkillRow.last_activity_at < used_at, used_at),
else_=SkillRow.last_activity_at,
),
updated_at=case(
(SkillRow.updated_at < used_at, used_at),
else_=SkillRow.updated_at,
),
)
)
await session.commit()
except Exception:
logger.debug("Failed to update skill usage projection for %r", name, exc_info=True)
def _schedule_use_projection_increment(name: str, use_count: int, used_at: datetime) -> None:
"""Best-effort bridge from synchronous sandbox tools to the DB home loop."""
try:
from deerflow.persistence.engine import fire_and_forget_db_write
fire_and_forget_db_write(_increment_use_projection(name, use_count, used_at))
except Exception:
logger.debug("Failed to schedule skill usage projection for %r", name, exc_info=True)
def runtime_use_event_key(runtime: Any | None) -> str | None:
"""Return the stable user-run identifier carried by ``ToolRuntime``."""
if runtime is None:
return None
context = getattr(runtime, "context", None)
if isinstance(context, dict):
for key in ("run_id", "langgraph_run_id"):
value = context.get(key)
if value is not None and str(value).strip():
return str(value).strip()
config = getattr(runtime, "config", None)
if isinstance(config, dict):
for bucket_name in ("configurable", "metadata"):
bucket = config.get(bucket_name)
if not isinstance(bucket, dict):
continue
for key in ("run_id", "langgraph_run_id"):
value = bucket.get(key)
if value is not None and str(value).strip():
return str(value).strip()
return None
def bump_use(name: str, *, event_key: str | None = None) -> bool:
"""Count one logical use, optionally de-duplicated by user run.
Returns ``True`` only when the counter changed. This makes callers and tests
able to distinguish a new invocation from a second file/script access in
the same run.
"""
normalized_name = str(name or "").strip()
if not normalized_name:
return False
normalized_event = str(event_key or "").strip() or None
dedupe_key = (normalized_event, normalized_name) if normalized_event else None
used_at = datetime.now(UTC)
new_count = 0
try:
with _usage_lock:
if dedupe_key is not None and dedupe_key in _recent_use_events:
_recent_use_events.move_to_end(dedupe_key)
return False
data = _read_all()
entry = {**_DEFAULT_ENTRY, **data.get(normalized_name, {})}
new_count = max(0, int(entry.get("use_count") or 0)) + 1
entry.update({"use_count": new_count, "last_used_at": used_at.isoformat()})
data[normalized_name] = entry
_write_all(data)
if dedupe_key is not None:
_recent_use_events[dedupe_key] = None
_recent_use_events.move_to_end(dedupe_key)
while len(_recent_use_events) > _MAX_RECENT_USE_EVENTS:
_recent_use_events.popitem(last=False)
except Exception:
logger.debug("Failed to bump usage entry for %r", normalized_name, exc_info=True)
return False
_schedule_use_projection_increment(normalized_name, new_count, used_at)
return True
def bump_patch(name: str) -> None:
@@ -0,0 +1,397 @@
"""Filesystem-backed version history for custom skills.
Only the active package lives below ``skills/custom``. Historical snapshots
are kept under the writable DeerFlow runtime directory, outside the canonical
skills tree and therefore outside every model-facing discovery/mount path.
The feature is deliberately gated by ``system_settings.skill_versioning``.
When the switch is off, callers keep the legacy write behaviour and this
module performs no snapshot writes.
"""
from __future__ import annotations
import hashlib
import json
import os
import shutil
import tempfile
import threading
from collections.abc import Iterator
from contextlib import contextmanager
from datetime import UTC, datetime
from pathlib import Path
from typing import Any
from uuid import uuid4
from deerflow.config.paths import get_paths
from deerflow.config.system_settings import load_system_settings
from deerflow.skills.storage import SkillStorage, get_or_new_skill_storage
from deerflow.skills.types import SKILL_MD_FILE, SkillCategory
_MANIFEST_FILE = "manifest.json"
_SCHEMA_VERSION = 1
_LOCKS_GUARD = threading.Lock()
_THREAD_LOCKS: dict[str, threading.RLock] = {}
def skill_versioning_enabled() -> bool:
"""Return the deployment-wide custom-skill versioning switch."""
try:
return bool(load_system_settings().skill_versioning.enabled)
except Exception:
return False
def _thread_lock(name: str) -> threading.RLock:
with _LOCKS_GUARD:
return _THREAD_LOCKS.setdefault(name, threading.RLock())
def _versions_root() -> Path:
return get_paths().base_dir / "skill-versions"
def _skill_root(name: str) -> Path:
return _versions_root() / SkillStorage.validate_skill_name(name)
def _manifest_path(name: str) -> Path:
return _skill_root(name) / _MANIFEST_FILE
def _version_dir(name: str, version: int) -> Path:
return _skill_root(name) / f"v{version:06d}"
@contextmanager
def _cross_process_lock(name: str) -> Iterator[None]:
"""Serialize one skill's snapshot/switch operations across workers."""
root = _skill_root(name)
root.mkdir(parents=True, exist_ok=True)
lock_path = root / ".lock"
with _thread_lock(name):
with lock_path.open("a+b") as handle:
if os.name == "nt": # pragma: no cover - exercised on Windows hosts
import msvcrt
if lock_path.stat().st_size == 0:
handle.write(b"0")
handle.flush()
handle.seek(0)
msvcrt.locking(handle.fileno(), msvcrt.LK_LOCK, 1)
else: # pragma: no cover - exercised in Linux CI/deployments
import fcntl
fcntl.flock(handle.fileno(), fcntl.LOCK_EX)
try:
yield
finally:
if os.name == "nt": # pragma: no cover
handle.seek(0)
msvcrt.locking(handle.fileno(), msvcrt.LK_UNLCK, 1)
else: # pragma: no cover
fcntl.flock(handle.fileno(), fcntl.LOCK_UN)
def _empty_manifest(name: str) -> dict[str, Any]:
return {
"schema_version": _SCHEMA_VERSION,
"skill_name": name,
"active_version": None,
"versions": [],
}
def _load_manifest(name: str) -> dict[str, Any]:
path = _manifest_path(name)
if not path.is_file():
return _empty_manifest(name)
try:
payload = json.loads(path.read_text(encoding="utf-8"))
except (OSError, json.JSONDecodeError) as exc:
raise ValueError(f"Skill version manifest for '{name}' is unreadable") from exc
if not isinstance(payload, dict) or payload.get("skill_name") != name:
raise ValueError(f"Skill version manifest for '{name}' is invalid")
versions = payload.get("versions")
if not isinstance(versions, list):
raise ValueError(f"Skill version manifest for '{name}' has invalid versions")
return payload
def _save_manifest(name: str, manifest: dict[str, Any]) -> None:
path = _manifest_path(name)
path.parent.mkdir(parents=True, exist_ok=True)
fd, tmp_name = tempfile.mkstemp(prefix=".manifest-", suffix=".tmp", dir=path.parent)
try:
with os.fdopen(fd, "w", encoding="utf-8") as handle:
json.dump(manifest, handle, ensure_ascii=False, indent=2, sort_keys=True)
handle.write("\n")
os.replace(tmp_name, path)
except Exception:
try:
os.unlink(tmp_name)
except OSError:
pass
raise
def _resolve_custom_dir(storage: SkillStorage, name: str) -> Path:
for skill in storage.load_skills(enabled_only=False):
if skill.name == name and skill.category == SkillCategory.CUSTOM:
return skill.skill_dir.resolve()
raise FileNotFoundError(f"Custom skill '{name}' not found")
def _tree_hash(root: Path) -> str:
digest = hashlib.sha256()
for path in sorted(root.rglob("*"), key=lambda item: item.relative_to(root).as_posix()):
relative = path.relative_to(root).as_posix()
if any(part in {"__pycache__", ".git"} for part in path.relative_to(root).parts):
continue
if path.is_symlink():
digest.update(b"L\0")
digest.update(relative.encode("utf-8"))
digest.update(b"\0")
digest.update(os.readlink(path).encode("utf-8", errors="surrogateescape"))
continue
if not path.is_file():
continue
digest.update(b"F\0")
digest.update(relative.encode("utf-8"))
digest.update(b"\0")
with path.open("rb") as handle:
while chunk := handle.read(1024 * 1024):
digest.update(chunk)
return digest.hexdigest()
def _copy_package(source: Path, destination: Path) -> None:
shutil.copytree(
source,
destination,
symlinks=True,
ignore=shutil.ignore_patterns("__pycache__", ".git"),
)
def record_custom_skill_version(
name: str,
*,
storage: SkillStorage | None = None,
action: str,
author: str | None = None,
summary: str | None = None,
) -> dict[str, Any] | None:
"""Snapshot the current custom package when it differs from active.
Returns the active/new version metadata. No-op (and no filesystem writes)
while the deployment switch is disabled.
"""
if not skill_versioning_enabled():
return None
name = SkillStorage.validate_skill_name(name)
storage = storage or get_or_new_skill_storage()
source = _resolve_custom_dir(storage, name)
current_hash = _tree_hash(source)
with _cross_process_lock(name):
manifest = _load_manifest(name)
active = next(
(item for item in manifest["versions"] if int(item.get("version") or 0) == int(manifest.get("active_version") or 0)),
None,
)
if active is not None and active.get("sha256") == current_hash:
return {**active, "active": True}
next_version = max([int(item.get("version") or 0) for item in manifest["versions"]] or [0]) + 1
destination = _version_dir(name, next_version)
staging = destination.parent / f".{destination.name}.staging-{uuid4().hex}"
_copy_package(source, staging)
try:
os.replace(staging, destination)
except Exception:
shutil.rmtree(staging, ignore_errors=True)
raise
now = datetime.now(UTC).isoformat()
entry = {
"version": next_version,
"sha256": current_hash,
"created_at": now,
"created_by": author,
"action": str(action or "update"),
"summary": str(summary or "").strip() or None,
"based_on_version": manifest.get("active_version"),
}
manifest["versions"].append(entry)
manifest["active_version"] = next_version
manifest["updated_at"] = now
_save_manifest(name, manifest)
return {**entry, "active": True}
def list_custom_skill_versions(
name: str,
*,
storage: SkillStorage | None = None,
author: str | None = None,
) -> dict[str, Any]:
"""Return newest-first metadata, lazily bootstrapping the current package."""
if not skill_versioning_enabled():
return {"enabled": False, "skill_name": name, "active_version": None, "versions": []}
storage = storage or get_or_new_skill_storage()
record_custom_skill_version(
name,
storage=storage,
action="baseline",
author=author,
summary="启用技能迭代时保存的当前版本",
)
with _cross_process_lock(name):
manifest = _load_manifest(name)
active_version = manifest.get("active_version")
versions = [{**item, "active": int(item.get("version") or 0) == int(active_version or 0)} for item in reversed(manifest["versions"])]
return {
"enabled": True,
"skill_name": name,
"active_version": active_version,
"versions": versions,
}
def activate_custom_skill_version(
name: str,
version: int,
*,
storage: SkillStorage | None = None,
) -> dict[str, Any]:
"""Materialize one historical snapshot as the sole model-visible package."""
if not skill_versioning_enabled():
raise RuntimeError("技能迭代功能未开启")
name = SkillStorage.validate_skill_name(name)
storage = storage or get_or_new_skill_storage()
target = _resolve_custom_dir(storage, name)
with _cross_process_lock(name):
manifest = _load_manifest(name)
entry = next(
(item for item in manifest["versions"] if int(item.get("version") or 0) == int(version)),
None,
)
if entry is None:
raise FileNotFoundError(f"Skill '{name}' version {version} not found")
source = _version_dir(name, int(version))
if not source.is_dir() or _tree_hash(source) != entry.get("sha256"):
raise ValueError(f"Skill '{name}' version {version} snapshot is missing or corrupted")
storage.validate_skill_markdown_content(
name,
(source / SKILL_MD_FILE).read_text(encoding="utf-8"),
)
if int(manifest.get("active_version") or 0) == int(version) and _tree_hash(target) == entry.get("sha256"):
return {**entry, "active": True}
parent = target.parent
staging = parent / f".{name}.version-stage-{uuid4().hex}"
backup = parent / f".{name}.version-backup-{uuid4().hex}"
_copy_package(source, staging)
moved_old = False
try:
os.replace(target, backup)
moved_old = True
os.replace(staging, target)
manifest["active_version"] = int(version)
manifest["updated_at"] = datetime.now(UTC).isoformat()
_save_manifest(name, manifest)
except Exception:
shutil.rmtree(staging, ignore_errors=True)
if moved_old:
shutil.rmtree(target, ignore_errors=True)
os.replace(backup, target)
raise
finally:
if backup.exists() and target.exists():
shutil.rmtree(backup, ignore_errors=True)
return {**entry, "active": True}
def delete_custom_skill_versions(name: str) -> None:
"""Remove stored snapshots after the custom skill itself is deleted."""
name = SkillStorage.validate_skill_name(name)
root = _skill_root(name)
if root.exists():
shutil.rmtree(root)
def reset_custom_skill_versions(
name: str,
*,
storage: SkillStorage | None = None,
author: str | None = None,
summary: str | None = None,
) -> dict[str, Any] | None:
"""Discard the previous chain and make the current package the new v1.
This is the explicit "direct overwrite" semantic offered beside
"iterate as a new version" for same-name uploads.
"""
if not skill_versioning_enabled():
return None
name = SkillStorage.validate_skill_name(name)
root = _skill_root(name)
with _cross_process_lock(name):
for child in list(root.iterdir()):
if child.name == ".lock":
continue
if child.is_dir():
shutil.rmtree(child)
else:
child.unlink(missing_ok=True)
return record_custom_skill_version(
name,
storage=storage,
action="overwrite",
author=author,
summary=summary or "直接覆盖后重置版本链",
)
def reconcile_custom_skill_versions(*, storage: SkillStorage | None = None, author: str | None = None) -> int:
"""Capture each current custom skill after the master switch is enabled."""
if not skill_versioning_enabled():
return 0
storage = storage or get_or_new_skill_storage()
captured = 0
for skill in storage.load_skills(enabled_only=False):
if skill.category != SkillCategory.CUSTOM:
continue
before = _load_manifest(skill.name).get("active_version") if _manifest_path(skill.name).exists() else None
result = record_custom_skill_version(
skill.name,
storage=storage,
action="feature_enabled",
author=author,
summary="技能迭代开关开启后捕获当前内容",
)
if result is not None and result.get("version") != before:
captured += 1
return captured
__all__ = [
"activate_custom_skill_version",
"delete_custom_skill_versions",
"list_custom_skill_versions",
"record_custom_skill_version",
"reconcile_custom_skill_versions",
"reset_custom_skill_versions",
"skill_versioning_enabled",
]
@@ -273,7 +273,16 @@ def skill_view_tool(name: str, runtime: ToolRuntime) -> str:
Args:
name: The skill name (hyphen-case, e.g. 'my-skill').
"""
return skill_view_impl(name, _resolve_active_agent_id(runtime), _resolve_extra_skills(runtime))
result = skill_view_impl(name, _resolve_active_agent_id(runtime), _resolve_extra_skills(runtime))
head = result.lstrip()[:200].lower()
if not ((head.startswith("skill '") and "not found" in head) or head.startswith("error reading skill")):
try:
from deerflow.skills.usage import bump_use, runtime_use_event_key
bump_use(name, event_key=runtime_use_event_key(runtime))
except Exception:
pass
return result
def _resolve_skills_container_base_path() -> str:
@@ -161,6 +161,26 @@ async def _publish_managed_skill(name: str, *, removed: bool = False) -> None:
await _sync_managed_skill_view(name)
async def _record_managed_skill_version(
storage: SkillStorage,
name: str,
*,
action: str,
author: str,
summary: str,
) -> None:
from deerflow.skills.versioning import record_custom_skill_version
await _to_thread(
record_custom_skill_version,
name,
storage=storage,
action=action,
author=author,
summary=summary,
)
async def _bump_patch_best_effort(name: str) -> None:
"""记一次技能维护活动(patch / edit)。
@@ -363,6 +383,14 @@ async def _skill_manage_impl(
# async stack — contextvars don't propagate into ``to_thread``.
if skill_store is not None:
await _ensure_skill_db_registered(skill_store, name, user_id)
skill_storage.invalidate_skills_cache()
await _record_managed_skill_version(
skill_storage,
name,
action="agent_create",
author=user_id,
summary="大模型创建技能",
)
await _publish_managed_skill(name)
return f"Created custom skill '{name}'."
@@ -378,6 +406,13 @@ async def _skill_manage_impl(
scan = await _scan_or_raise(content, executable=False, location=f"{name}/{SKILL_MD_FILE}")
skill_file = skill_storage.get_custom_skill_file(name)
prev_content = await _to_thread(skill_file.read_text, encoding="utf-8")
await _record_managed_skill_version(
skill_storage,
name,
action="baseline",
author=user_id,
summary="大模型编辑前的活动版本",
)
await _to_thread(skill_storage.write_custom_skill, name, SKILL_MD_FILE, content)
await _to_thread(
skill_storage.append_history,
@@ -385,6 +420,13 @@ async def _skill_manage_impl(
_history_record(action="edit", file_path=SKILL_MD_FILE, prev_content=prev_content, new_content=content, thread_id=thread_id, scanner=scan),
)
await _bump_patch_best_effort(name)
await _record_managed_skill_version(
skill_storage,
name,
action="agent_edit",
author=user_id,
summary="大模型编辑 SKILL.md",
)
await _publish_managed_skill(name)
return f"Updated custom skill '{name}'."
@@ -406,6 +448,13 @@ async def _skill_manage_impl(
new_content = prev_content.replace(find, replace, replacement_count)
await _to_thread(skill_storage.validate_skill_markdown_content, name, new_content)
scan = await _scan_or_raise(new_content, executable=False, location=f"{name}/{SKILL_MD_FILE}")
await _record_managed_skill_version(
skill_storage,
name,
action="baseline",
author=user_id,
summary="大模型修补前的活动版本",
)
await _to_thread(skill_storage.write_custom_skill, name, SKILL_MD_FILE, new_content)
await _to_thread(
skill_storage.append_history,
@@ -413,6 +462,13 @@ async def _skill_manage_impl(
_history_record(action="patch", file_path=SKILL_MD_FILE, prev_content=prev_content, new_content=new_content, thread_id=thread_id, scanner=scan),
)
await _bump_patch_best_effort(name)
await _record_managed_skill_version(
skill_storage,
name,
action="agent_patch",
author=user_id,
summary="大模型修补 SKILL.md",
)
await _publish_managed_skill(name)
return f"Patched custom skill '{name}' ({replacement_count} replacement(s) applied, {occurrences} match(es) found)."
@@ -453,6 +509,12 @@ async def _skill_manage_impl(
await skill_store.delete(name, user_id)
except Exception:
logger.debug("Failed to delete DB row for %r", name, exc_info=True)
try:
from deerflow.skills.versioning import delete_custom_skill_versions
await _to_thread(delete_custom_skill_versions, name)
except Exception:
logger.debug("Failed to delete version history for %r", name, exc_info=True)
agent_store = _default_agent_store()
if agent_store is not None:
try:
@@ -482,12 +544,26 @@ async def _skill_manage_impl(
prev_content = await _to_thread(target.read_text, encoding="utf-8") if exists else None
executable = "scripts/" in path or path.startswith("scripts/")
scan = await _scan_or_raise(content, executable=executable, location=f"{name}/{path}")
await _record_managed_skill_version(
skill_storage,
name,
action="baseline",
author=user_id,
summary="大模型写文件前的活动版本",
)
await _to_thread(skill_storage.write_custom_skill, name, path, content)
await _to_thread(
skill_storage.append_history,
name,
_history_record(action="write_file", file_path=path, prev_content=prev_content, new_content=content, thread_id=thread_id, scanner=scan),
)
await _record_managed_skill_version(
skill_storage,
name,
action="agent_write_file",
author=user_id,
summary=f"大模型写入文件 {path}",
)
await _sync_managed_skill_view(name)
return f"Wrote '{path}' for custom skill '{name}'."
@@ -502,12 +578,26 @@ async def _skill_manage_impl(
if not await _to_thread(target.exists):
raise FileNotFoundError(f"Supporting file '{path}' not found for skill '{name}'.")
prev_content = await _to_thread(target.read_text, encoding="utf-8")
await _record_managed_skill_version(
skill_storage,
name,
action="baseline",
author=user_id,
summary="大模型删文件前的活动版本",
)
await _to_thread(target.unlink)
await _to_thread(
skill_storage.append_history,
name,
_history_record(action="remove_file", file_path=path, prev_content=prev_content, new_content=None, thread_id=thread_id, scanner={"decision": "allow", "reason": "Deletion requested."}),
)
await _record_managed_skill_version(
skill_storage,
name,
action="agent_remove_file",
author=user_id,
summary=f"大模型删除文件 {path}",
)
await _sync_managed_skill_view(name)
return f"Removed '{path}' from custom skill '{name}'."
@@ -5,26 +5,28 @@ import pytest
from deerflow.config.app_config import AppConfig
_SKILL_VIEW_KEYS = ("skill_view_reuse_enabled", "skill_view_cache_enabled")
_OPT_IN_KEYS = ("model_timing_nonblocking_enabled", "asyncio_thread_pool_enabled", "tool_metrics_enabled")
_DEFAULT_ON_KEYS = (*_SKILL_VIEW_KEYS, "tool_metrics_enabled", "skill_metrics_enabled")
_OPT_IN_KEYS = ("model_timing_nonblocking_enabled", "asyncio_thread_pool_enabled")
def test_missing_runtime_performance_enables_skill_view_only():
def test_missing_runtime_performance_enables_skill_view_and_skill_metrics():
config = AppConfig(sandbox={"use": "deerflow.sandbox.local:LocalSandboxProvider"})
assert config.runtime_performance.model_dump() == {
"skill_view_reuse_enabled": True,
"skill_view_cache_enabled": True,
"tool_metrics_enabled": False,
"tool_metrics_enabled": True,
"skill_metrics_enabled": True,
"model_timing_nonblocking_enabled": False,
"asyncio_thread_pool_enabled": False,
"asyncio_thread_pool_size": 100,
}
@pytest.mark.parametrize("key", [*_SKILL_VIEW_KEYS, *_OPT_IN_KEYS])
@pytest.mark.parametrize("key", [*_DEFAULT_ON_KEYS, *_OPT_IN_KEYS])
def test_runtime_performance_switches_are_independent(tmp_path: Path, key: str):
# Skill-view switches default on, so independence is checked by turning
# one of them off. The opt-in switches default off and are turned on.
enabled = key not in _SKILL_VIEW_KEYS
# Skill-view and audit metrics default on, so independence is checked by
# turning one off. Opt-in switches default off and are turned on.
enabled = key not in _DEFAULT_ON_KEYS
config_path = tmp_path / "config.yaml"
config_path.write_text(
f"sandbox:\n use: deerflow.sandbox.local:LocalSandboxProvider\nruntime_performance:\n {key}: {'true' if enabled else 'false'}\n",
@@ -32,7 +34,7 @@ def test_runtime_performance_switches_are_independent(tmp_path: Path, key: str):
)
flags = AppConfig.from_file(str(config_path)).runtime_performance.model_dump()
assert flags[key] is enabled
for other in _SKILL_VIEW_KEYS:
for other in _DEFAULT_ON_KEYS:
if other != key:
assert flags[other] is True
for other in _OPT_IN_KEYS:
@@ -0,0 +1,95 @@
"""Regression coverage for model-independent skill usage attribution."""
from __future__ import annotations
from pathlib import Path
from types import SimpleNamespace
import pytest
from deerflow.sandbox import tools
from deerflow.skills import usage
from deerflow.tools.builtins import skill_tools
@pytest.fixture(autouse=True)
def _clear_recent_use_events():
usage._recent_use_events.clear()
yield
usage._recent_use_events.clear()
def test_bump_use_counts_a_skill_once_per_run_and_syncs_the_catalog(tmp_path: Path, monkeypatch):
usage_path = tmp_path / ".usage.json"
projected: list[tuple[str, int, object]] = []
monkeypatch.setattr(usage, "_usage_path", lambda: usage_path)
monkeypatch.setattr(
usage,
"_schedule_use_projection_increment",
lambda name, use_count, used_at: projected.append((name, use_count, used_at)),
)
assert usage.bump_use("page-generator", event_key="run-1") is True
assert usage.bump_use("page-generator", event_key="run-1") is False
assert usage.bump_use("page-generator", event_key="run-2") is True
entry = usage.get_entry("page-generator")
assert entry["use_count"] == 2
assert entry["last_used_at"]
assert [(name, count) for name, count, _used_at in projected] == [
("page-generator", 1),
("page-generator", 2),
]
def test_skill_file_and_script_paths_record_public_and_custom_skills(monkeypatch):
calls: list[tuple[str, str | None]] = []
monkeypatch.setattr(
usage,
"bump_use",
lambda name, *, event_key=None: calls.append((name, event_key)),
)
runtime = SimpleNamespace(context={"run_id": "run-weak-model"}, config={})
tools._record_skill_read("/mnt/skills/public/report-maker/SKILL.md", runtime)
tools._record_skill_command(
"python /mnt/skills/custom/data-cleaner/scripts/run.py --fast",
runtime,
)
assert calls == [
("report-maker", "run-weak-model"),
("data-cleaner", "run-weak-model"),
]
def test_skill_view_counts_as_use_without_model_narration(monkeypatch):
calls: list[tuple[str, str | None]] = []
runtime = SimpleNamespace(context={"run_id": "run-skill-view"}, config={})
monkeypatch.setattr(skill_tools, "skill_view_impl", lambda *_args, **_kwargs: "skill instructions")
monkeypatch.setattr(
usage,
"bump_use",
lambda name, *, event_key=None: calls.append((name, event_key)),
)
result = skill_tools.skill_view_tool.func(name="report-maker", runtime=runtime)
assert result == "skill instructions"
assert calls == [("report-maker", "run-skill-view")]
def test_failed_skill_view_does_not_count_as_use(monkeypatch):
calls: list[str] = []
runtime = SimpleNamespace(context={"run_id": "run-missing"}, config={})
monkeypatch.setattr(
skill_tools,
"skill_view_impl",
lambda *_args, **_kwargs: "Skill 'missing' not found.",
)
monkeypatch.setattr(usage, "bump_use", lambda name, **_kwargs: calls.append(name))
result = skill_tools.skill_view_tool.func(name="missing", runtime=runtime)
assert result == "Skill 'missing' not found."
assert calls == []
@@ -288,7 +288,7 @@ def _tool_sandbox(tmp_path: Path, view_root: Path, monkeypatch: pytest.MonkeyPat
monkeypatch.setattr(tools, "is_local_sandbox", lambda _runtime: True)
monkeypatch.setattr(tools, "is_host_bash_allowed", lambda: True)
monkeypatch.setattr(tools, "get_thread_data", lambda _runtime: {"workspace_path": str(tmp_path / "workspace"), "uploads_path": str(tmp_path / "uploads"), "outputs_path": str(tmp_path / "outputs")})
monkeypatch.setattr(tools, "_record_skill_read", lambda _path: None)
monkeypatch.setattr(tools, "_record_skill_read", lambda *_args: None)
monkeypatch.setattr(tools, "_get_skills_container_path", lambda: "/mnt/skills")
(tmp_path / "workspace").mkdir(exist_ok=True)
assert view_root.is_dir()
@@ -326,6 +326,30 @@ def test_bash_runs_the_updated_skill_script(cache_setup, monkeypatch, tmp_path):
assert (view.root / "public" / "online" / "scripts" / "run.py").read_text(encoding="utf-8") == "print('two')\n"
def test_bash_records_a_direct_skill_script_invocation(cache_setup, monkeypatch, tmp_path):
root, _config, storage = cache_setup
script = root / "public" / "online" / "scripts"
script.mkdir()
(script / "run.py").write_text("print('used')\n", encoding="utf-8")
view = skill_view.refresh_skill_sandbox_view(storage=storage)
_tool_sandbox(tmp_path, view.root, monkeypatch)
recorded: list[tuple[str, object]] = []
monkeypatch.setattr(
tools,
"_record_skill_command",
lambda command, runtime: recorded.append((command, runtime)),
)
result = tools.bash_tool.func(
runtime=None,
description="test",
command="python /mnt/skills/public/online/scripts/run.py",
)
assert result == "ok"
assert recorded == [("python /mnt/skills/public/online/scripts/run.py", None)]
def test_bash_rejects_an_offline_skill(cache_setup, monkeypatch, tmp_path):
root, config, storage = cache_setup
_skill(root, "offline")
@@ -50,3 +50,21 @@ def test_canonical_write_file_is_still_recorded(monkeypatch) -> None:
middleware.wrap_tool_call(_request("write_file"), lambda _: _result("write_file"))
flush.assert_called_once()
def test_call_metrics_switch_skips_new_metric_rows(monkeypatch) -> None:
middleware = ToolMetricsMiddleware()
flush = Mock()
monkeypatch.setattr(middleware, "_flush", flush)
monkeypatch.setattr(
"deerflow.agents.middlewares.tool_metrics_middleware.get_call_metrics_settings",
lambda: SimpleNamespace(enabled=False),
)
result = middleware.wrap_tool_call(
_request("write_file"),
lambda _: _result("write_file"),
)
assert result.name == "write_file"
flush.assert_not_called()
@@ -20,8 +20,10 @@ from deerflow.config.app_config import AppConfig
BUILDERS = [build_lead_runtime_middlewares, build_subagent_runtime_middlewares]
def _config(enabled=None):
def _config(enabled=None, *, skill_enabled=None):
options = {} if enabled is None else {"tool_metrics_enabled": enabled}
if skill_enabled is not None:
options["skill_metrics_enabled"] = skill_enabled
return AppConfig(
sandbox={"use": "deerflow.sandbox.local:LocalSandboxProvider"},
runtime_performance=options,
@@ -29,18 +31,29 @@ def _config(enabled=None):
@pytest.mark.parametrize("builder", BUILDERS)
@pytest.mark.parametrize("enabled", [None, False])
def test_paused_runtime_never_constructs_a_recorder(builder, enabled, monkeypatch):
def test_explicitly_paused_runtime_never_constructs_a_recorder(builder, monkeypatch):
constructor = Mock(side_effect=AssertionError("paused runtime constructed a DB recorder"))
monkeypatch.setattr(metrics, "ToolMetricsMiddleware", constructor)
middlewares = builder(app_config=_config(enabled))
middlewares = builder(app_config=_config(False, skill_enabled=False))
constructor.assert_not_called()
assert any(isinstance(m, ToolErrorHandlingMiddleware) for m in middlewares)
assert any(isinstance(m, LlmMetricsMiddleware) for m in middlewares)
@pytest.mark.parametrize("builder", BUILDERS)
def test_default_runtime_keeps_a_full_tool_and_skill_recorder(builder):
recorders = [
middleware
for middleware in builder(app_config=_config())
if isinstance(middleware, metrics.ToolMetricsMiddleware)
]
assert len(recorders) == 1
assert recorders[0]._skill_only is False
def _tool_wrappers(builder, enabled):
# Exercise the actual error/audit wrappers selected by both runtime builders.
return [m for m in builder(app_config=_config(enabled)) if isinstance(m, (ToolErrorHandlingMiddleware, metrics.ToolMetricsMiddleware))]
@@ -77,6 +90,30 @@ def test_sync_tool_execution_and_error_conversion_survive_pause(builder, enabled
assert flushed.call_args.args[0].status == result.status
@pytest.mark.parametrize("builder", BUILDERS)
def test_skill_only_mode_records_a_path_based_skill_call(builder, monkeypatch):
flushed = Mock()
monkeypatch.setattr(metrics.ToolMetricsMiddleware, "_flush", lambda _, record: flushed(record))
request = SimpleNamespace(
tool_call={
"id": "call-skill",
"name": "bash",
"args": {"command": "python /mnt/skills/public/report-maker/scripts/run.py"},
}
)
expected = ToolMessage(content="ok", tool_call_id="call-skill", name="bash")
def handler(_request):
return expected
for middleware in reversed(_tool_wrappers(builder, False)):
handler = partial(middleware.wrap_tool_call, handler=handler)
assert handler(request) is expected
assert flushed.call_count == 1
assert flushed.call_args.args[0].skill_name == "report-maker"
@pytest.mark.asyncio
@pytest.mark.parametrize("builder", BUILDERS)
@pytest.mark.parametrize("enabled", [False, True])