aria-code 0.52.0__py3-none-any.whl

aria_code/packages/aria_skills/loader.py

@@ -0,0 +1,455 @@
+"""Discover, verify, match, and activate portable SKILL.md workflows."""
+
+from __future__ import annotations
+
+from collections import deque
+from dataclasses import dataclass, field
+from datetime import datetime, timezone
+import hashlib
+import json
+import os
+from pathlib import Path
+import re
+from typing import Iterable, Sequence
+from aria_code.packages.aria_core.paths import aria_home
+
+
+#: Basic file I/O and deliverable-export tools that stay available no matter
+#: which skill is active or what its `allowed_tools` policy declares.
+#:
+#: Why: a skill's allowed_tools is a *domain* policy (which market-data/
+#: research tools may run), not a statement about whether the model may read
+#: or write files. Observed failure: the "equity-research-report" skill's
+#: policy listed only research tools; matched on the CJK term "报告" against
+#: a user request to convert an *existing* file to PDF; once activated it
+#: silently stripped read_file/write_file from the tool schema, and the model
+#: could only reply "please paste the file contents" — it had no idea the
+#: tool had been taken away. Keeping these core tools exempt means a
+#: mismatched skill activation degrades to "runs extra irrelevant workflow
+#: steps" instead of "loses the ability to read a file the user pointed to".
+CORE_FILE_TOOLS: frozenset[str] = frozenset({
+    "read_file", "analyze_file", "write_file", "edit_file", "multi_edit",
+    "write_spreadsheet", "export_markdown_pdf",
+})
+
+_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]{0,63}$")
+_QUALIFIED_NAME_RE = re.compile(
+    r"^[a-z0-9][a-z0-9-]{0,63}:[a-z0-9][a-z0-9-]{0,63}$"
+)
+_MAX_SKILL_CHARS = 20_000
+_ACTIVATION_HISTORY: deque["SkillActivationTrace"] = deque(maxlen=100)
+_LATIN_STOP_WORDS = {
+    "about", "after", "also", "and", "any", "create", "does", "for", "from",
+    "into", "only", "report", "request", "skill", "that", "the", "this", "use",
+    "user", "when", "with",
+}
+# CJK equivalents of the above. Without these, a Chinese request scores almost
+# entirely on function words: "帮我设计一个牙科诊所的网站" once ranked
+# `strategy-generation` (a trading-strategy skill) above `ui-asset-sourcing` on
+# the strength of 一个/帮我/设计 alone, because Chinese has no spaces and the
+# n-gram tokenizer below emits every 2-4 char window — so polite framing like
+# 帮我 also produces 帮我设, 帮我设计, 我设, 我设计, multiplying a single
+# meaningless phrase into several "matches".
+_CJK_STOP_WORDS = {
+    "一个", "一下", "一些", "个", "什么", "可以", "如何", "帮我", "帮我做", "帮我设",
+    "帮忙", "我们", "我的", "我想", "我要", "我设", "我需要", "怎么", "怎样",
+    "应该", "开始", "我", "然后", "现在", "生成", "用我", "的", "目前", "看看",
+    "给我", "请求", "需要", "麻烦", "这个", "那个", "项目", "使用", "进行",
+}
+_IGNORED_TREE_NAMES = {".DS_Store", ".pytest_cache", "__pycache__"}
+
+
+@dataclass(frozen=True)
+class SkillPolicy:
+    allowed_tools: tuple[str, ...] = ()
+    permissions: tuple[str, ...] = ()
+    # Specialist agents this skill expects to orchestrate, by registry name.
+    # Mirrors SkillSpec.agents in ..registry, which has carried the same
+    # skill→agent relationship for the built-in specs all along; this makes the
+    # portable SKILL.md catalog able to express it too. Advisory only — the
+    # loader never imports the agent registry, because it must keep working in
+    # runtimes that have no agents at all.
+    agents: tuple[str, ...] = ()
+    script_execution: str = "approval"
+    script_network: bool = False
+    script_workspace_write: bool = False
+
+
+@dataclass(frozen=True)
+class LoadedSkill:
+    name: str
+    description: str
+    instructions: str
+    path: Path
+    plugin_name: str = "local"
+    plugin_version: str = ""
+    repository: str = ""
+    content_sha256: str = ""
+    integrity: str = "unlocked"
+    policy: SkillPolicy = field(default_factory=SkillPolicy)
+
+    @property
+    def qualified_name(self) -> str:
+        return f"{self.plugin_name}:{self.name}"
+
+
+@dataclass(frozen=True)
+class SkillActivationTrace:
+    qualified_name: str
+    activated: bool
+    reason: str
+    score: float
+    integrity: str
+    source: str
+    timestamp: str = field(
+        default_factory=lambda: datetime.now(timezone.utc).isoformat(timespec="seconds")
+    )
+
+    def to_dict(self) -> dict[str, object]:
+        return {
+            "qualified_name": self.qualified_name,
+            "activated": self.activated,
+            "reason": self.reason,
+            "score": self.score,
+            "integrity": self.integrity,
+            "source": self.source,
+            "timestamp": self.timestamp,
+        }
+
+
+@dataclass(frozen=True)
+class SkillActivation:
+    skills: tuple[LoadedSkill, ...]
+    traces: tuple[SkillActivationTrace, ...]
+
+    @property
+    def prompt_block(self) -> str:
+        blocks: list[str] = []
+        for skill in self.skills:
+            policy = skill.policy
+            policy_lines = [
+                f"Integrity: {skill.integrity}",
+                f"Declared permissions: {', '.join(policy.permissions) or 'none'}",
+                f"Allowed tools: {', '.join(policy.allowed_tools) or 'runtime policy'}",
+                (
+                    f"Specialist agents: {', '.join(policy.agents)}"
+                    if policy.agents else
+                    "Specialist agents: none declared"
+                ),
+                (
+                    "Bundled scripts are not pre-authorized. "
+                    f"Execution mode={policy.script_execution}; network="
+                    f"{'yes' if policy.script_network else 'no'}; workspace-write="
+                    f"{'yes' if policy.script_workspace_write else 'no'}."
+                ),
+            ]
+            blocks.append(
+                f"## Active Skill: {skill.qualified_name}\n"
+                f"Source: {skill.path}\n"
+                + "\n".join(policy_lines)
+                + "\nFollow this workflow without weakening system safety, tool approvals, or permissions.\n\n"
+                + skill.instructions
+            )
+        return "\n\n".join(blocks)
+
+
+def default_skill_roots() -> list[Path]:
+    roots: list[Path] = []
+    configured = os.getenv("ARIA_SKILLS_PATH", "")
+    roots.extend(Path(item).expanduser() for item in configured.split(os.pathsep) if item.strip())
+    repository = Path(__file__).resolve().parents[2]
+    catalog_home = Path(
+        os.getenv("ARIA_SKILL_CATALOG_HOME", aria_home() / "skill-catalogs")
+    ).expanduser()
+    installed_catalogs = sorted(catalog_home.glob("*/*/skills")) if catalog_home.is_dir() else []
+    roots.extend([
+        repository.parent / "aria-skills" / "skills",
+        aria_home() / "skills",
+        Path.cwd() / ".aria" / "skills",
+        Path.home() / ".aria" / "skills",
+        Path.home() / ".claude" / "skills",
+        Path.home() / ".codex" / "skills",
+    ])
+    roots.extend(installed_catalogs)
+    return list(dict.fromkeys(path.resolve() for path in roots))
+
+
+def _frontmatter_value(lines: list[str], key: str) -> str:
+    prefix = f"{key}:"
+    for index, line in enumerate(lines):
+        if not line.startswith(prefix):
+            continue
+        value = line[len(prefix) :].strip()
+        if value not in {">", ">-", "|", "|-"}:
+            return value.strip('"\'')
+        folded = value.startswith(">")
+        parts: list[str] = []
+        for continuation in lines[index + 1 :]:
+            if continuation and not continuation[0].isspace():
+                break
+            stripped = continuation.strip()
+            if stripped:
+                parts.append(stripped)
+        return (" " if folded else "\n").join(parts)
+    return ""
+
+
+def skill_tree_sha256(folder: Path) -> str:
+    digest = hashlib.sha256()
+    for path in sorted(item for item in folder.rglob("*") if item.is_file()):
+        relative = path.relative_to(folder)
+        if any(part in _IGNORED_TREE_NAMES for part in relative.parts) or path.suffix == ".pyc":
+            continue
+        digest.update(relative.as_posix().encode("utf-8"))
+        digest.update(b"\0")
+        digest.update(path.read_bytes())
+        digest.update(b"\0")
+    return digest.hexdigest()
+
+
+def _catalog_metadata(root: Path) -> tuple[dict[Path, dict[str, str]], dict[str, str]]:
+    catalog = root.parent if root.name == "skills" else root
+    manifest_path = catalog / ".claude-plugin" / "marketplace.json"
+    lock_path = catalog / ".claude-plugin" / "skills.lock.json"
+    mapping: dict[Path, dict[str, str]] = {}
+    locks: dict[str, str] = {}
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        catalog_version = str((manifest.get("metadata") or {}).get("version") or "")
+        catalog_repository = str(
+            (manifest.get("metadata") or {}).get("repository")
+            or (manifest.get("owner") or {}).get("url")
+            or ""
+        )
+        for plugin in manifest.get("plugins") or []:
+            plugin_name = str(plugin.get("name") or "local")
+            plugin_version = str(plugin.get("version") or catalog_version)
+            repository = str(plugin.get("repository") or plugin.get("homepage") or catalog_repository)
+            for skill_path in plugin.get("skills") or []:
+                resolved = (catalog / str(skill_path)).resolve()
+                mapping[resolved] = {
+                    "plugin_name": plugin_name,
+                    "plugin_version": plugin_version,
+                    "repository": repository,
+                }
+    except (OSError, json.JSONDecodeError, TypeError):
+        pass
+    try:
+        lock = json.loads(lock_path.read_text(encoding="utf-8"))
+        for qualified_name, entry in (lock.get("skills") or {}).items():
+            if isinstance(entry, dict) and entry.get("sha256"):
+                locks[str(qualified_name)] = str(entry["sha256"])
+    except (OSError, json.JSONDecodeError, TypeError):
+        pass
+    return mapping, locks
+
+
+def _load_policy(folder: Path) -> SkillPolicy:
+    try:
+        payload = json.loads((folder / "skill-policy.json").read_text(encoding="utf-8"))
+    except (OSError, json.JSONDecodeError, TypeError):
+        return SkillPolicy()
+    scripts = payload.get("scripts") or {}
+    return SkillPolicy(
+        allowed_tools=tuple(str(item) for item in payload.get("allowed_tools") or []),
+        permissions=tuple(str(item) for item in payload.get("permissions") or []),
+        agents=tuple(str(item) for item in payload.get("agents") or []),
+        script_execution=str(scripts.get("execution") or "approval"),
+        script_network=bool(scripts.get("network", False)),
+        script_workspace_write=bool(scripts.get("workspace_write", False)),
+    )
+
+
+def _parse_skill(
+    path: Path,
+    metadata: dict[str, str] | None = None,
+    locks: dict[str, str] | None = None,
+) -> LoadedSkill | None:
+    try:
+        text = path.read_text(encoding="utf-8")
+    except OSError:
+        return None
+    if len(text) > _MAX_SKILL_CHARS or not text.startswith("---\n"):
+        return None
+    end = text.find("\n---\n", 4)
+    if end < 0:
+        return None
+    frontmatter = text[4:end].splitlines()
+    name = _frontmatter_value(frontmatter, "name")
+    description = _frontmatter_value(frontmatter, "description")
+    if not _NAME_RE.fullmatch(name) or not description:
+        return None
+    instructions = text[end + 5 :].strip()
+    if not instructions:
+        return None
+    metadata = metadata or {}
+    plugin_name = metadata.get("plugin_name") or "local"
+    if not _NAME_RE.fullmatch(plugin_name):
+        plugin_name = "local"
+    qualified_name = f"{plugin_name}:{name}"
+    content_sha256 = skill_tree_sha256(path.parent)
+    expected = (locks or {}).get(qualified_name)
+    integrity = "verified" if expected == content_sha256 else "mismatch" if expected else "unlocked"
+    return LoadedSkill(
+        name=name,
+        description=description,
+        instructions=instructions,
+        path=path,
+        plugin_name=plugin_name,
+        plugin_version=metadata.get("plugin_version", ""),
+        repository=metadata.get("repository", ""),
+        content_sha256=content_sha256,
+        integrity=integrity,
+        policy=_load_policy(path.parent),
+    )
+
+
+def discover_external_skills(roots: Sequence[Path] | None = None) -> list[LoadedSkill]:
+    found: dict[str, LoadedSkill] = {}
+    for raw_root in roots or default_skill_roots():
+        root = Path(raw_root).expanduser().resolve()
+        if not root.is_dir():
+            continue
+        mapping, locks = _catalog_metadata(root)
+        for candidate in sorted(root.glob("*/SKILL.md")):
+            loaded = _parse_skill(candidate, mapping.get(candidate.parent.resolve()), locks)
+            if loaded and loaded.qualified_name not in found:
+                found[loaded.qualified_name] = loaded
+    return list(found.values())
+
+
+def _requested_skill_names(message: str) -> set[str]:
+    return set(
+        re.findall(
+            r"\$([a-z0-9][a-z0-9-]{0,63}(?::[a-z0-9][a-z0-9-]{0,63})?)\b",
+            message.lower(),
+        )
+    )
+
+
+def _quoted_phrases(description: str) -> list[str]:
+    return [
+        next(group for group in match.groups() if group is not None).strip().lower()
+        for match in re.finditer(r'"([^"]+)"|“([^”]+)”|\'([^\']+)\'', description)
+    ]
+
+
+def _terms(text: str) -> set[str]:
+    low = text.lower()
+    latin = {
+        token for token in re.findall(r"[a-z0-9][a-z0-9_-]{2,}", low)
+        if token not in _LATIN_STOP_WORDS
+    }
+    cjk: set[str] = set()
+    for chunk in re.findall(r"[\u3400-\u9fff]{2,}", low):
+        if len(chunk) <= 8:
+            cjk.add(chunk)
+        for size in (2, 3, 4):
+            cjk.update(chunk[index : index + size] for index in range(len(chunk) - size + 1))
+    cjk -= _CJK_STOP_WORDS
+    # An n-gram that merely *contains* a stop word is usually noise too:
+    # "\u5e2e\u6211\u8bbe\u8ba1" is \u5e2e\u6211 + \u8bbe\u8ba1 with no extra signal, yet it scores as its own
+    # distinct match. Drop windows that are a stop word plus at most one
+    # character, which is where that inflation comes from.
+    cjk = {
+        gram for gram in cjk
+        if not any(
+            stop in gram and len(gram) - len(stop) <= 1
+            for stop in _CJK_STOP_WORDS
+        )
+    }
+    return latin | cjk
+
+
+def _match_score(message: str, skill: LoadedSkill) -> tuple[float, str]:
+    low = message.lower()
+    for phrase in _quoted_phrases(skill.description):
+        if len(phrase) >= 2 and phrase in low:
+            return 20.0 + min(len(phrase), 20) / 10, f'description phrase "{phrase}"'
+    overlap = _terms(message) & _terms(skill.description)
+    if not overlap:
+        return 0.0, "no metadata overlap"
+    score = float(len(overlap))
+    if len(overlap) >= 2:
+        score += 2.0
+    return score, f"metadata overlap: {', '.join(sorted(overlap)[:6])}"
+
+
+def activate_external_skills(
+    message: str,
+    skills: Iterable[LoadedSkill] | None = None,
+    max_skills: int = 2,
+    record: bool = True,
+) -> SkillActivation:
+    available = list(skills if skills is not None else discover_external_skills())
+    requested = _requested_skill_names(message)
+    by_short_name: dict[str, list[LoadedSkill]] = {}
+    for skill in available:
+        by_short_name.setdefault(skill.name, []).append(skill)
+
+    candidates: list[tuple[float, str, LoadedSkill]] = []
+    traces: list[SkillActivationTrace] = []
+    for skill in available:
+        explicit_qualified = skill.qualified_name in requested
+        explicit_short = skill.name in requested and len(by_short_name[skill.name]) == 1
+        if explicit_qualified or explicit_short:
+            score, reason = 100.0, "explicit invocation"
+        else:
+            score, reason = _match_score(message, skill)
+        if score < 4.0:
+            continue
+        if skill.integrity == "mismatch":
+            traces.append(SkillActivationTrace(
+                qualified_name=skill.qualified_name,
+                activated=False,
+                reason="integrity mismatch",
+                score=score,
+                integrity=skill.integrity,
+                source=str(skill.path),
+            ))
+            continue
+        if skill.integrity == "unlocked" and not (explicit_qualified or explicit_short):
+            traces.append(SkillActivationTrace(
+                qualified_name=skill.qualified_name,
+                activated=False,
+                reason="automatic activation requires an integrity lock",
+                score=score,
+                integrity=skill.integrity,
+                source=str(skill.path),
+            ))
+            continue
+        candidates.append((score, reason, skill))
+
+    candidates.sort(key=lambda item: (-item[0], item[2].qualified_name))
+    selected = candidates[: max(1, max_skills)]
+    for score, reason, skill in selected:
+        traces.append(SkillActivationTrace(
+            qualified_name=skill.qualified_name,
+            activated=True,
+            reason=reason,
+            score=round(score, 2),
+            integrity=skill.integrity,
+            source=str(skill.path),
+        ))
+    if record:
+        _ACTIVATION_HISTORY.extend(traces)
+    return SkillActivation(
+        skills=tuple(item[2] for item in selected),
+        traces=tuple(traces),
+    )
+
+
+def select_external_skills(
+    message: str,
+    skills: Iterable[LoadedSkill] | None = None,
+) -> list[LoadedSkill]:
+    return list(activate_external_skills(message, skills).skills)
+
+
+def build_skill_prompt_block(message: str) -> str:
+    return activate_external_skills(message).prompt_block
+
+
+def recent_skill_activation_traces(limit: int = 20) -> list[SkillActivationTrace]:
+    bounded = max(1, min(int(limit), len(_ACTIVATION_HISTORY) or 1))
+    return list(_ACTIVATION_HISTORY)[-bounded:]

aria_code/packages/aria_skills/registry.py

@@ -0,0 +1,84 @@
+"""Skill manifests for model-facing workflows."""
+
+from __future__ import annotations
+
+from dataclasses import dataclass, field
+from typing import List
+
+from aria_code.packages.aria_core import CapabilityManifest, PermissionLevel, ServiceKind
+
+
+@dataclass(frozen=True)
+class SkillSpec:
+    name: str
+    description: str
+    tools: List[str] = field(default_factory=list)
+    agents: List[str] = field(default_factory=list)
+    permissions: List[PermissionLevel] = field(default_factory=list)
+
+    def manifest(self) -> CapabilityManifest:
+        return CapabilityManifest(
+            name=self.name,
+            kind=ServiceKind.SKILL,
+            description=self.description,
+            capabilities=[f"tool:{name}" for name in self.tools] + [f"agent:{name}" for name in self.agents],
+            permissions=self.permissions,
+            required_services=self.tools + self.agents,
+            tags=["skill"],
+        )
+
+
+def builtin_skill_specs() -> List[SkillSpec]:
+    return [
+        SkillSpec(
+            name="financial-research",
+            description="Multi-source quote, fundamentals, technical analysis, and narrative report generation.",
+            tools=["get_market_data", "get_market_history", "get_risk_metrics", "analyze_news"],
+            agents=["technical", "fundamental", "macro", "risk", "synthesis"],
+            permissions=[PermissionLevel.NETWORK],
+        ),
+        SkillSpec(
+            name="equity-research-report",
+            description=(
+                "Evidence-backed equity report workflow with specialist agents, "
+                "deterministic fallbacks, provenance, critique, and completion gates."
+            ),
+            tools=[
+                "get_market_data",
+                "get_market_history",
+                "calculate_factors",
+                "get_risk_metrics",
+                "analyze_news",
+            ],
+            agents=[
+                "technical",
+                "fundamental",
+                "macro",
+                "risk",
+                "news",
+                "catalyst",
+                "sector",
+                "synthesis",
+            ],
+            permissions=[PermissionLevel.NETWORK, PermissionLevel.WORKSPACE_WRITE],
+        ),
+        SkillSpec(
+            name="strategy-backtest",
+            description="Generate and validate trading strategies with historical simulation and artifacts.",
+            tools=["get_market_data"],
+            agents=["technical", "risk"],
+            permissions=[PermissionLevel.NETWORK, PermissionLevel.WORKSPACE_WRITE],
+        ),
+        SkillSpec(
+            name="workspace-coding",
+            description="Read, edit, and verify local project files with explicit workspace permissions.",
+            tools=["read_file", "list_files", "search_code", "edit_file", "write_file", "run_command"],
+            permissions=[PermissionLevel.READ_ONLY, PermissionLevel.WORKSPACE_WRITE],
+        ),
+        SkillSpec(
+            name="broker-portfolio",
+            description="Read broker account state and propose guarded orders with user approval.",
+            tools=["broker_query", "broker_order"],
+            permissions=[PermissionLevel.BROKER_READ, PermissionLevel.BROKER_TRADE],
+        ),
+    ]

aria_code/packages/aria_tools/__init__.py

@@ -0,0 +1,5 @@
+"""Tool registry facade for Aria Code."""
+
+from .registry import ToolSpec, ToolRegistry, build_registry_from_legacy
+
+__all__ = ["ToolSpec", "ToolRegistry", "build_registry_from_legacy"]

aria_code/packages/aria_tools/financial/__init__.py

@@ -0,0 +1,8 @@
+"""Financial tools package."""
+
+from .factors import run_factor_research
+from .risk_tools import run_risk_profile
+from .compliance import run_compliance_audit
+from .strategy import validate_strategy_spec
+
+__all__ = ["run_factor_research", "run_risk_profile", "run_compliance_audit", "validate_strategy_spec"]

aria_code/packages/aria_tools/financial/_paths.py

@@ -0,0 +1,130 @@
+"""定位 aria-skills 脚本与 Arthera SDK —— 替掉四个工具文件里写死的绝对路径。
+
+2026-08-19：本目录下 factors / risk_tools / strategy / compliance 四个文件
+各自硬编码了开发者本机的绝对路径 —— 指向 aria-skills 的脚本，以及 Arthera
+SDK 的安装位置。aria-code 是公开仓库，这带来两个问题：
+
+  1. 功能上，任何别人 clone 下来这些路径都不存在，工具静默降级成
+     "Error: 脚本不存在"，而错误信息里还打印出一个跟对方毫无关系的路径。
+  2. 信息上，公开仓库里出现开发者本机用户名，以及一个私有仓库
+     (Arthera) 的存在与目录结构。
+
+skill 那边其实早就有一套正规的发现顺序 —— packages/aria_skills/loader.py
+的 default_skill_roots()（ARIA_SKILLS_PATH 环境变量 → 同级 aria-skills
+checkout → ~/.arthera/skills → ~/.claude/skills → …）。这里直接复用它，
+而不是再写第二套查找逻辑，免得两处顺序不一致时出现"CLI 能发现这个 skill、
+工具却找不到它的脚本"。
+
+Arthera SDK 是私有仓库的东西，公开仓库无从假设它在哪，因此只认显式的
+ARTHERA_SDK_PATH，外加一个同级 checkout 的兜底；找不到就安静跳过 —— 这些
+工具本来就有 mcp_tool 的 ImportError 兜底分支，SDK 缺失不该是致命错误。
+"""
+
+from __future__ import annotations
+
+import os
+import sys
+from pathlib import Path
+from aria_code.packages.aria_core.paths import aria_home
+
+__all__ = ["find_skill_script", "missing_script_message", "ensure_arthera_sdk", "ensure_arthera_root"]
+
+
+def _skill_roots() -> list[Path]:
+    """优先复用 skill loader 的发现顺序；它不可用时退化为等价的最小实现。"""
+    try:
+        from packages.aria_skills.loader import default_skill_roots
+
+        return [Path(p) for p in default_skill_roots()]
+    except Exception:
+        roots: list[Path] = []
+        configured = os.getenv("ARIA_SKILLS_PATH", "")
+        roots.extend(
+            Path(item).expanduser() for item in configured.split(os.pathsep) if item.strip()
+        )
+        repository = Path(__file__).resolve().parents[3]
+        roots.extend([
+            repository.parent / "aria-skills" / "skills",
+            aria_home() / "skills",
+            Path.home() / ".aria" / "skills",
+            Path.home() / ".claude" / "skills",
+        ])
+        return roots
+
+
+def find_skill_script(skill_name: str, script_name: str) -> Path | None:
+    """返回 <某个 skill 根>/<skill_name>/scripts/<script_name>，找不到返回 None。
+
+    调用方负责把 None 变成对用户有意义的提示——这里不抛异常，因为"本机没装
+    这个 skill 目录"是完全正常的部署形态，不是错误。
+    """
+    for root in _skill_roots():
+        candidate = root / skill_name / "scripts" / script_name
+        try:
+            if candidate.is_file():
+                return candidate
+        except OSError:
+            continue
+    return None
+
+
+def missing_script_message(skill_name: str, script_name: str) -> str:
+    """脚本缺失时给出可操作的提示，而不是打印一条别人机器上不存在的路径。"""
+    return (
+        f"Error: 找不到 {skill_name}/scripts/{script_name}。"
+        " 请获取 aria-skills 目录，并用 ARIA_SKILLS_PATH 指向其中的 skills/，"
+        "或把它放在 aria-code 的同级目录下。"
+    )
+
+
+def ensure_arthera_sdk() -> bool:
+    """把 Arthera SDK 加进 sys.path。返回是否找到。
+
+    只认显式配置 + 同级 checkout：Arthera 是私有仓库，公开仓库不该假设它
+    存在于某个固定绝对路径。
+    """
+    candidates: list[Path] = []
+    configured = os.getenv("ARTHERA_SDK_PATH", "")
+    if configured.strip():
+        candidates.append(Path(configured).expanduser())
+    arthera_root = os.getenv("ARTHERA_PATH", "")
+    if arthera_root.strip():
+        candidates.append(Path(arthera_root).expanduser() / "sdks" / "python")
+    candidates.append(Path(__file__).resolve().parents[3].parent / "Arthera" / "sdks" / "python")
+
+    for candidate in candidates:
+        try:
+            if candidate.is_dir():
+                path_str = str(candidate)
+                if path_str not in sys.path:
+                    sys.path.append(path_str)
+                return True
+        except OSError:
+            continue
+    return False
+
+
+def ensure_arthera_root() -> bool:
+    """把 Arthera 仓库根目录加进 sys.path，让 ``packages.*`` 可导入。返回是否找到。
+
+    跟 ``ensure_arthera_sdk`` 同样的理由：Arthera 是私有仓库，公开仓库不该假设
+    它在某个写死的绝对路径上。这里认的是 ``ARTHERA_ROOT``（doctor.py 与
+    backtest_cmds.py 已经在用的同一个变量），外加一个同级 checkout 的兜底。
+    """
+    candidates: list[Path] = []
+    for var in ("ARTHERA_ROOT", "ARTHERA_PATH"):
+        configured = os.getenv(var, "")
+        if configured.strip():
+            candidates.append(Path(configured).expanduser())
+    candidates.append(Path(__file__).resolve().parents[4].parent / "Arthera")
+
+    for candidate in candidates:
+        try:
+            if candidate.is_dir():
+                path_str = str(candidate)
+                if path_str not in sys.path:
+                    sys.path.insert(0, path_str)
+                return True
+        except OSError:
+            continue
+    return False