aria-code 0.167.0__py3-none-win_amd64.whl

aria_code/apps/cli/preflight.py

@@ -0,0 +1,502 @@
+"""Intent-aware dependency preflight for Aria CLI.
+
+This module is intentionally pure and side-effect free: it detects likely user
+intent, checks local availability, and returns install guidance. It never
+installs packages or mutates config.
+"""
+from __future__ import annotations
+
+from dataclasses import dataclass
+import importlib.util
+import os
+import shlex
+import shutil
+from typing import Callable, Iterable, Mapping
+
+from aria_code.apps.cli.intent_router import build_intent_route, detect_intents
+
+
+ModuleChecker = Callable[[str], bool]
+CommandChecker = Callable[[str], bool]
+EnvGetter = Callable[[str], str | None]
+
+
+@dataclass(frozen=True)
+class PythonRequirement:
+    module: str
+    package: str
+    purpose: str
+    required: bool = True
+
+
+@dataclass(frozen=True)
+class CommandRequirement:
+    command: str
+    install_hint: str
+    purpose: str
+    required: bool = True
+
+
+@dataclass(frozen=True)
+class EnvRequirement:
+    name: str
+    purpose: str
+    required: bool = False
+
+
+@dataclass(frozen=True)
+class IntentPreflight:
+    intents: tuple[str, ...]
+    services: tuple[str, ...]
+    python: tuple[PythonRequirement, ...]
+    commands: tuple[CommandRequirement, ...]
+    env: tuple[EnvRequirement, ...]
+    missing_python: tuple[PythonRequirement, ...]
+    missing_commands: tuple[CommandRequirement, ...]
+    missing_env: tuple[EnvRequirement, ...]
+
+    @property
+    def has_findings(self) -> bool:
+        return bool(self.missing_python or self.missing_commands or self.missing_env)
+
+    @property
+    def has_required_findings(self) -> bool:
+        return any(req.required for req in self.missing_python + self.missing_commands + self.missing_env)
+
+    def pip_install_command(self) -> str:
+        packages: list[str] = []
+        seen: set[str] = set()
+        for req in self.missing_python:
+            if req.package not in seen:
+                packages.append(req.package)
+                seen.add(req.package)
+        if not packages:
+            return ""
+        return "python3 -m pip install " + " ".join(shlex.quote(pkg) for pkg in packages)
+
+
+@dataclass(frozen=True)
+class InstallPlan:
+    """User-confirmed install guidance derived from an intent preflight."""
+
+    services: tuple[str, ...]
+    pip_packages: tuple[str, ...]
+    pip_command: str
+    command_hints: tuple[str, ...]
+    env_hints: tuple[str, ...]
+    has_required_items: bool
+
+    @property
+    def has_actions(self) -> bool:
+        return bool(self.pip_packages or self.command_hints or self.env_hints)
+
+
+@dataclass(frozen=True)
+class InstallSelection:
+    """Resolved user selection for Python package installation."""
+
+    pip_packages: tuple[str, ...]
+    skipped_packages: tuple[str, ...] = ()
+    mode: str = "all"
+
+    @property
+    def has_packages(self) -> bool:
+        return bool(self.pip_packages)
+
+
+_PY_REQS: Mapping[str, PythonRequirement] = {
+    "aiohttp": PythonRequirement("aiohttp", "aiohttp", "异步 HTTP 请求"),
+    "requests": PythonRequirement("requests", "requests", "HTTP 请求"),
+    "pandas": PythonRequirement("pandas", "pandas", "表格与行情数据处理"),
+    "numpy": PythonRequirement("numpy", "numpy", "数值计算"),
+    "yfinance": PythonRequirement("yfinance", "yfinance", "美股/港股/ETF/加密行情"),
+    "akshare": PythonRequirement("akshare", "akshare", "A 股与中文市场数据"),
+    "matplotlib": PythonRequirement("matplotlib", "matplotlib", "PNG 静态图表渲染", required=False),
+    "mplfinance": PythonRequirement("mplfinance", "mplfinance", "K 线 PNG 渲染", required=False),
+    "PIL": PythonRequirement("PIL", "Pillow", "图片读取与剪贴板图片"),
+    "mss": PythonRequirement("mss", "mss", "屏幕截图"),
+    "pyautogui": PythonRequirement("pyautogui", "pyautogui", "桌面自动化"),
+    "playwright": PythonRequirement("playwright", "playwright", "浏览器自动化"),
+    "openpyxl": PythonRequirement("openpyxl", "openpyxl", "Excel 文件解析"),
+    "pdfplumber": PythonRequirement("pdfplumber", "pdfplumber", "PDF 文本与表格解析", required=False),
+    "pypdf": PythonRequirement("pypdf", "pypdf", "PDF 解析备用引擎", required=False),
+    "docx": PythonRequirement("docx", "python-docx", "Word/DOCX 文件解析"),
+    "bs4": PythonRequirement("bs4", "beautifulsoup4", "HTML 文件解析"),
+    "duckdb": PythonRequirement("duckdb", "duckdb", "本地分析型 SQL"),
+    "vectorbt": PythonRequirement("vectorbt", "vectorbt", "增强向量化回测", required=False),
+    "alpaca": PythonRequirement("alpaca", "alpaca-py", "Alpaca 券商连接"),
+    "tigeropen": PythonRequirement("tigeropen", "tigeropen", "Tiger 券商连接"),
+    "longbridge": PythonRequirement("longbridge", "longbridge", "Longbridge 券商连接"),
+    "ib_insync": PythonRequirement("ib_insync", "ib_insync", "IBKR 券商连接"),
+    "futu": PythonRequirement("futu", "futu-api", "富途券商连接"),
+    "webull": PythonRequirement("webull", "webull", "Webull 券商连接"),
+    "easytrader": PythonRequirement("easytrader", "easytrader", "A 股交易客户端连接"),
+    "ddgs": PythonRequirement("ddgs", "ddgs", "零配置联网搜索 (web_search 工具)", required=False),
+    "ccxt": PythonRequirement("ccxt", "ccxt", "加密货币交易所行情/资金费率", required=False),
+}
+
+_CMD_REQS: Mapping[str, CommandRequirement] = {
+    "ollama": CommandRequirement("ollama", "https://ollama.com/download", "本地模型运行"),
+    "node": CommandRequirement("node", "brew install node", "部分 MCP server 运行时", required=False),
+    "gh": CommandRequirement("gh", "brew install gh && gh auth login", "GitHub PR/Issue/CI 操作"),
+    "playwright": CommandRequirement("playwright", "python3 -m playwright install chromium", "安装 Chromium 浏览器内核", required=False),
+}
+
+_BROKER_MODULES = {
+    "alpaca": ("alpaca", ("alpaca", "alpaca-py")),
+    "tiger": ("tigeropen", ("tiger", "老虎", "tigeropen")),
+    "longbridge": ("longbridge", ("longbridge", "长桥")),
+    "ibkr": ("ib_insync", ("ibkr", "interactive brokers", "盈透")),
+    "futu": ("futu", ("futu", "富途")),
+    "webull": ("webull", ("webull",)),
+    "easytrader": ("easytrader", ("easytrader", "同花顺", "雪球")),
+}
+
+
+def package_to_module(package: str) -> str:
+    """Map a pip package name to its import module name (e.g. Pillow → PIL)."""
+    for req in _PY_REQS.values():
+        if req.package == package:
+            return req.module
+    # Common fallbacks for packages not in _PY_REQS
+    _COMMON = {
+        "duckduckgo-search": "duckduckgo_search",
+        "scikit-learn": "sklearn",
+        "beautifulsoup4": "bs4",
+        "python-docx": "docx",
+        "Pillow": "PIL",
+        "futu-api": "futu",
+        "alpaca-py": "alpaca",
+    }
+    if package in _COMMON:
+        return _COMMON[package]
+    return package.replace("-", "_")
+
+
+def _default_module_available(module: str) -> bool:
+    return importlib.util.find_spec(module) is not None
+
+
+def _default_command_available(command: str) -> bool:
+    return shutil.which(command) is not None
+
+
+def _add_req(target: list[PythonRequirement], key: str) -> None:
+    req = _PY_REQS[key]
+    if not any(item.module == req.module for item in target):
+        target.append(req)
+
+
+def _add_cmd(target: list[CommandRequirement], key: str) -> None:
+    req = _CMD_REQS[key]
+    if not any(item.command == req.command for item in target):
+        target.append(req)
+
+
+def _contains_any(text: str, keywords: Iterable[str]) -> bool:
+    return any(keyword in text for keyword in keywords)
+
+
+def _detect_intents(message: str) -> tuple[str, ...]:
+    return detect_intents(message)
+
+
+def build_intent_preflight(
+    message: str,
+    *,
+    module_available: ModuleChecker | None = None,
+    command_available: CommandChecker | None = None,
+    env_get: EnvGetter | None = None,
+) -> IntentPreflight:
+    """Build an intent-aware dependency report for a user request."""
+    module_available = module_available or _default_module_available
+    command_available = command_available or _default_command_available
+    env_get = env_get or os.environ.get
+
+    low = message.lower().strip()
+    route = build_intent_route(message)
+    intents = route.intents
+    python_reqs: list[PythonRequirement] = []
+    command_reqs: list[CommandRequirement] = []
+    env_reqs: list[EnvRequirement] = []
+    services: list[str] = list(route.services)
+
+    def service(name: str) -> None:
+        if name not in services:
+            services.append(name)
+
+    if any(i in intents for i in ("market_snapshot", "market_analysis", "chart", "dashboard", "report", "backtest", "strategy", "market_research")):
+        service("market_data")
+        _add_req(python_reqs, "pandas")
+        _add_req(python_reqs, "numpy")
+        _add_req(python_reqs, "yfinance")
+        if any(ch in low for ch in ("a股", "沪", "深", ".sz", ".ss", "港股", "宁德时代", "贵州茅台")):
+            _add_req(python_reqs, "akshare")
+
+    if "chart" in intents:
+        service("chart_renderer")
+        if _contains_any(low, ("png", "图片", "静态", "k线", "candlestick")):
+            _add_req(python_reqs, "matplotlib")
+            _add_req(python_reqs, "mplfinance")
+
+    if "dashboard" in intents:
+        service("dashboard_generator")
+        _add_req(python_reqs, "akshare")
+
+    if "report" in intents:
+        service("report_generator")
+        _add_req(python_reqs, "matplotlib")
+
+    if "backtest" in intents or "strategy" in intents:
+        service("backtest_engine")
+        _add_req(python_reqs, "vectorbt")
+
+    if "vision" in intents:
+        service("vision_input")
+        _add_req(python_reqs, "PIL")
+
+    if "screenshot" in intents:
+        service("screenshot")
+        _add_req(python_reqs, "PIL")
+        _add_req(python_reqs, "mss")
+
+    if "browser" in intents:
+        service("browser")
+        _add_req(python_reqs, "playwright")
+        _add_req(python_reqs, "PIL")
+        _add_cmd(command_reqs, "playwright")
+
+    if "file_analysis" in intents:
+        service("file_parser")
+        # Request only the parser needed by the referenced file type.  Listing
+        # every possible parser for two DOCX files made preflight look like a
+        # system audit and led users to install unrelated PDF/Excel packages.
+        if _contains_any(low, (".xlsx", ".xls", " excel", "excel文件")):
+            _add_req(python_reqs, "pandas")
+            _add_req(python_reqs, "openpyxl")
+        if _contains_any(low, (".csv", ".tsv", "csv文件")):
+            _add_req(python_reqs, "pandas")
+        if _contains_any(low, (".pdf", "pdf文件")):
+            _add_req(python_reqs, "pdfplumber")
+            _add_req(python_reqs, "pypdf")
+        if _contains_any(low, (".docx", ".doc", "word文件", "word文档")):
+            _add_req(python_reqs, "docx")
+        if _contains_any(low, (".html", ".htm", "html文件")):
+            _add_req(python_reqs, "bs4")
+        if _contains_any(low, (".png", ".jpg", ".jpeg", ".webp", "图片文件")):
+            _add_req(python_reqs, "PIL")
+
+    for _, (module, aliases) in _BROKER_MODULES.items():
+        if _contains_any(low, aliases):
+            service("broker_connector")
+            _add_req(python_reqs, module)
+
+    if "github" in intents:
+        service("github_cli")
+        _add_cmd(command_reqs, "gh")
+
+    if "mcp" in intents:
+        service("mcp")
+        _add_cmd(command_reqs, "node")
+
+    if "local_model" in intents:
+        service("local_llm")
+        _add_cmd(command_reqs, "ollama")
+
+    if "cloud" in intents:
+        service("cloud_runtime")
+        env_reqs.append(EnvRequirement("ALIYUN_ACCESS_KEY_ID", "阿里云访问密钥", required=False))
+
+    if "web_search" in intents:
+        service("web_search")
+        _add_req(python_reqs, "ddgs")
+        env_reqs.append(EnvRequirement("BRAVE_SEARCH_API_KEY", "Brave 搜索 (免费 2000 次/月，比 DuckDuckGo 更稳定)", required=False))
+
+    if "crypto" in intents:
+        service("crypto_data")
+        _add_req(python_reqs, "ccxt")
+
+    if "sports" in intents:
+        service("sports_data")
+        env_reqs.append(EnvRequirement("FOOTBALL_DATA_API_KEY", "football-data.org 实时赛程/积分榜 (免费注册)", required=False))
+
+    missing_python = tuple(req for req in python_reqs if not module_available(req.module))
+    missing_commands = tuple(req for req in command_reqs if not command_available(req.command))
+    missing_env = tuple(req for req in env_reqs if not env_get(req.name))
+
+    return IntentPreflight(
+        intents=intents,
+        services=tuple(services),
+        python=tuple(python_reqs),
+        commands=tuple(command_reqs),
+        env=tuple(env_reqs),
+        missing_python=missing_python,
+        missing_commands=missing_commands,
+        missing_env=missing_env,
+    )
+
+
+def build_full_dependency_report(
+    *,
+    module_available: ModuleChecker | None = None,
+    command_available: CommandChecker | None = None,
+    env_get: EnvGetter | None = None,
+    include_optional: bool = True,
+) -> IntentPreflight:
+    """Scan every known requirement (intent-independent) for a full health check.
+
+    Used by `/install` with no arguments — reports all missing packages/tools
+    across the whole project, not just those implied by a single message.
+    """
+    module_available = module_available or _default_module_available
+    command_available = command_available or _default_command_available
+    env_get = env_get or os.environ.get
+
+    # Broker SDKs are intent-specific — a user only needs the one for their
+    # broker, so a generic full scan should not propose installing all of them.
+    _broker_modules = {module for module, _ in _BROKER_MODULES.values()}
+    python_reqs = tuple(
+        r for r in _PY_REQS.values() if r.module not in _broker_modules
+    )
+    command_reqs = tuple(_CMD_REQS.values())
+    env_reqs: tuple[EnvRequirement, ...] = (
+        EnvRequirement("BRAVE_SEARCH_API_KEY", "Brave 联网搜索 (免费 2000 次/月)", required=False),
+        EnvRequirement("FOOTBALL_DATA_API_KEY", "football-data.org 实时足球数据", required=False),
+    )
+
+    def _keep(req) -> bool:
+        return include_optional or getattr(req, "required", True)
+
+    missing_python = tuple(
+        r for r in python_reqs if _keep(r) and not module_available(r.module)
+    )
+    missing_commands = tuple(
+        r for r in command_reqs if _keep(r) and not command_available(r.command)
+    )
+    missing_env = tuple(r for r in env_reqs if not env_get(r.name))
+
+    return IntentPreflight(
+        intents=("full_scan",),
+        services=("all",),
+        python=python_reqs,
+        commands=command_reqs,
+        env=env_reqs,
+        missing_python=missing_python,
+        missing_commands=missing_commands,
+        missing_env=missing_env,
+    )
+
+
+def build_install_plan(report: IntentPreflight) -> InstallPlan:
+    """Convert preflight findings into explicit user-approved install steps."""
+    packages: list[str] = []
+    seen: set[str] = set()
+    for req in report.missing_python:
+        if req.package not in seen:
+            packages.append(req.package)
+            seen.add(req.package)
+
+    command_hints = tuple(
+        f"{req.command}: {req.install_hint}"
+        for req in report.missing_commands
+    )
+    env_hints = tuple(
+        f"{req.name}: {req.purpose}"
+        for req in report.missing_env
+    )
+    pip_command = ""
+    if packages:
+        pip_command = "python3 -m pip install " + " ".join(shlex.quote(pkg) for pkg in packages)
+
+    return InstallPlan(
+        services=report.services,
+        pip_packages=tuple(packages),
+        pip_command=pip_command,
+        command_hints=command_hints,
+        env_hints=env_hints,
+        has_required_items=report.has_required_findings,
+    )
+
+
+def select_install_packages(
+    plan: InstallPlan,
+    report: IntentPreflight | None = None,
+    *,
+    mode: str = "all",
+    custom: Iterable[str] | None = None,
+) -> InstallSelection:
+    """Resolve selector choices into concrete pip packages.
+
+    Modes:
+    - all: install every missing Python package in the plan
+    - required: install only required Python packages
+    - optional: install only optional Python packages
+    - custom: install only packages named in ``custom`` if present in the plan
+    - skip/plan: install nothing
+    """
+    available = list(plan.pip_packages)
+    normalized_mode = (mode or "all").strip().lower()
+    if normalized_mode in {"skip", "none", "cancel", "plan", "dry-run", "dry_run"}:
+        return InstallSelection((), tuple(available), normalized_mode)
+
+    if normalized_mode == "required" and report is not None:
+        selected = [
+            req.package for req in report.missing_python
+            if req.required and req.package in available
+        ]
+    elif normalized_mode == "optional" and report is not None:
+        selected = [
+            req.package for req in report.missing_python
+            if not req.required and req.package in available
+        ]
+    elif normalized_mode == "custom":
+        wanted = {str(item).strip() for item in (custom or []) if str(item).strip()}
+        selected = [pkg for pkg in available if pkg in wanted]
+    else:
+        selected = available
+
+    selected = list(dict.fromkeys(selected))
+    skipped = [pkg for pkg in available if pkg not in selected]
+    return InstallSelection(tuple(selected), tuple(skipped), normalized_mode)
+
+
+def format_preflight_plain(report: IntentPreflight) -> str:
+    """Return a concise plain-text preflight message."""
+    if not report.has_findings:
+        return ""
+    plan = build_install_plan(report)
+
+    if not report.has_required_findings:
+        lines = ["可选增强未安装；当前任务会继续使用内置或降级实现。"]
+        if report.missing_python:
+            reqs = "、".join(f"{r.package}（{r.purpose}）" for r in report.missing_python)
+            lines.append("增强包：" + reqs)
+        if report.missing_commands:
+            tools = ", ".join(plan.command_hints)
+            lines.append("增强工具：" + tools)
+        if report.missing_env:
+            envs = ", ".join(plan.env_hints)
+            lines.append("可选配置：" + envs)
+        if plan.pip_packages:
+            lines.append("需要时运行 /install --auto；安装会进入 Aria 当前环境。")
+        elif plan.has_actions:
+            lines.append("需要时运行 /setup 查看配置向导。")
+        return "\n".join(lines)
+
+    lines = ["本次任务缺少必要能力："]
+    if report.missing_python:
+        for req in report.missing_python:
+            requirement = "必要" if req.required else "可选"
+            lines.append(f"- {req.package}：{req.purpose}（{requirement}）")
+    if report.missing_commands:
+        for hint in plan.command_hints:
+            lines.append("- " + hint)
+    if report.missing_env:
+        envs = ", ".join(plan.env_hints)
+        lines.append("可选配置：" + envs)
+    if plan.has_actions:
+        if plan.pip_packages:
+            lines.append("运行 /install --auto 安装到 Aria 当前环境；完成后会自动刷新工具能力。")
+        else:
+            lines.append("运行 /setup 查看配置向导；Aria 不会静默修改系统环境。")
+    return "\n".join(lines)

aria_code/apps/cli/project_aria.py

@@ -0,0 +1,60 @@
+"""
+Project-level ARIA.md helpers.
+
+Used by /init scaffolds and repository bootstrap to keep project memory files
+structured and consistent.
+"""
+from __future__ import annotations
+
+
+def build_project_aria_md(
+    *,
+    project_name: str,
+    stack: str,
+    entry: str = "main.py",
+    purpose: str = "",
+    notes: list[str] | None = None,
+    conventions: list[str] | None = None,
+) -> str:
+    """Build a durable project-level ARIA.md template."""
+    notes = notes or []
+    conventions = conventions or [
+        "Keep CLI output stable and avoid leaking local paths in normal UI.",
+        "Prefer thin CLI entry points plus command mixins for implementation.",
+        "Treat turn envelopes, traces, exports, and provider health as shared contracts.",
+    ]
+
+    lines = [
+        "# Memory",
+        "",
+        f"- **Project**: {project_name}",
+        f"- **Stack**: {stack}",
+        f"- **Entry**: {entry}",
+    ]
+    if purpose:
+        lines.append(f"- **Purpose**: {purpose}")
+    lines.append("- **Conventions**:")
+    lines.extend(f"  - {item}" for item in conventions)
+    if notes:
+        lines.append("- **Notes**:")
+        lines.extend(f"  - {item}" for item in notes)
+
+    lines.extend([
+        "",
+        "## Memory Layers",
+        "- Project ARIA.md describes this repository and overrides the global profile when both apply.",
+        "- `~/.arthera/ARIA.md` is the user profile and carries cross-project preferences.",
+        "- Session history and traces stay ephemeral unless exported explicitly.",
+        "",
+        "## Operational Rules",
+        "- Keep generated code and user artifacts in the user's workspace, not in the source tree, unless the user asks otherwise.",
+        "- Prefer deterministic service output envelopes for CLI, trace, and export surfaces.",
+        "- Use `/doctor` or the health views before trusting external providers.",
+        "",
+        "## Workflow Notes",
+        "- Use `/init` to refresh project context after substantial structural changes.",
+        "- Use `/memory add` for durable project facts and `/memory profile` for user preferences.",
+        "- Keep long sessions compacted and avoid relying on chat history as the only source of truth.",
+        "",
+    ])
+    return "\n".join(lines)

aria_code/apps/cli/prompt_assembly.py

@@ -0,0 +1,78 @@
+"""Turn-prompt assembly DECISIONS for send_message (pure, testable).
+
+Extracted from ``aria_cli.send_message``. These functions decide what text is
+actually sent to the model for a turn — the precedence between analysis-
+commentary mode, a decomposition plan, and the raw message, plus whether a
+file-tool hint or a fetched ML-signal block gets prepended. All of it is pure
+string assembly: the upstream decisions (whether analysis was requested,
+what the decomposition plan says, what the ML signal text is) are computed
+elsewhere and passed in here as plain values, so none of this needs I/O,
+``self`` state, or mocking to test.
+"""
+
+from __future__ import annotations
+
+ANALYSIS_COMMENTARY_PROMPT_ZH = (
+    "请基于上方已获取的实时行情数据提供深度分析（约300字）："
+    " 当前价格位置与短期趋势判断、多空力量对比"
+    "（若涉及多标的则对比两者强弱）、关键支撑/阻力位、操作建议（附风险提示）。"
+    " 直接开始分析，不要重复表格数据。"
+)
+
+
+ANALYSIS_COMMENTARY_PROMPT_EN = (
+    "Using the market data just fetched, give an analysis of about 300 words:"
+    " where the price stands and the short-term trend, the balance of buyers and"
+    " sellers (comparing the instruments if there are several), key support and"
+    " resistance, and a suggested course of action with its risks."
+    " Start with the analysis; do not repeat the table."
+)
+
+
+def build_base_message(
+    message: str,
+    *,
+    wants_analysis_commentary: bool,
+    decomposition_plan: str = "",
+    snapshot: str = "",
+    lang: str = "zh",
+) -> str:
+    """Pick the effective prompt body for this turn.
+
+    Precedence: analysis-commentary mode wins outright (the snapshot data was
+    already shown, so the model just needs the fixed commentary instruction —
+    a decomposition plan would be redundant). Otherwise a non-empty
+    decomposition plan is prefixed onto the raw message. Otherwise the raw
+    message is sent unchanged.
+    """
+    if wants_analysis_commentary:
+        # The data goes in the prompt itself. The instruction used to say "the
+        # data above", but the turn's history is conversation[:-1], and after a
+        # pre-fetch the last entry IS the data — so the model was asked to
+        # comment on figures it never received.
+        en = not str(lang).lower().startswith("zh")
+        prompt = ANALYSIS_COMMENTARY_PROMPT_EN if en else ANALYSIS_COMMENTARY_PROMPT_ZH
+        if snapshot.strip():
+            prompt += ("\n\n[Market data]\n" if en else "\n\n[行情数据]\n") + snapshot.strip()
+        return prompt
+    if decomposition_plan:
+        return f"[执行计划]\n{decomposition_plan}\n\n[用户请求]\n{message}"
+    return message
+
+
+def should_prepend_file_tool_hint(
+    wants_analysis_commentary: bool,
+    reference_context: str,
+) -> bool:
+    """A file-tool hint is only useful when the model doesn't already have
+    situational grounding — skip it in analysis-commentary mode (grounded by
+    the snapshot) and whenever ``@``-reference context is present (grounded
+    by the referenced files)."""
+    return not wants_analysis_commentary and not reference_context
+
+
+def with_ml_signal_prefix(current_message: str, ml_signal_text: str) -> str:
+    """Prepend a fetched ML-signal reference block, if one was fetched."""
+    if not ml_signal_text:
+        return current_message
+    return f"[ML信号参考 — 仅供分析参考，非投资建议]\n{ml_signal_text}\n\n{current_message}"