fix: version-gate stock analysis specifications

Author: yjw

CHANGELOG.md

@@ -5,6 +5,14 @@ All notable changes to this project will be documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## [0.2.2] - 2026-06-18
+
+### Fixed
+- Made stock-analysis updates strictly version-gated: remote content is installed only when its semantic version is greater than the verified local version.
+- Downloaded the reporting specification, output discipline, data-source strategy, M1-M6 methodology, and templates as one text-only bundle.
+- Added SHA-256 manifests and read-time validation for the cached methodology bundle; failures retain the last verified local or bundled specification.
+- Kept the security boundary explicit: no remote Python, JavaScript, shell code, package, or repository checkout is executed by report generation.
+
 ## [0.2.1] - 2026-06-18
 
 ### Added

README.md

@@ -219,10 +219,12 @@ The report follows the six-module method from
 5. M5 market/portfolio style
 6. M6 resilient directions
 
-Before each LLM replay, young checks the remote `stock-analysis` `SKILL.md`. A newer text specification is cached
-under `~/.young_stock/methodologies/stock-analysis/` and used for report structure and writing discipline. Remote
-code is never executed; if the check is unavailable, the most recent cached specification or the bundled 4.2.0
-guidance is used.
+Before each LLM replay, young checks the remote `stock-analysis` version. It installs a text-only update only when
+the remote semantic version is greater than the locally cached/bundled version. `SKILL.md`, output discipline,
+data-source strategy, M1-M6 methodology files, and report templates are downloaded together, SHA-256 recorded in
+`~/.young_stock/methodologies/stock-analysis/manifest.json`, and verified when read. Remote code is never executed.
+If checking, downloading, or validation fails, young keeps the last verified local specification or bundled 4.2.0
+guidance.
 
 Each module has an evidence score. Missing fields remain missing rather than being rendered as zero. Low-quality
 evidence automatically produces a shorter report limited to verified indices, holdings, risks, and next-session

pyproject.toml

@@ -4,7 +4,7 @@ build-backend = "hatchling.build"
 
 [project]
 name = "young-stock-cli"
-version = "0.2.1"
+version = "0.2.2"
 description = "A-share (China stock market) after-hours CLI — no login, no scraping tricks, just data."
 readme = "README.md"
 requires-python = ">=3.9"

src/young_stock/__init__.py

@@ -1,3 +1,3 @@
 """young-stock-cli: A-share after-hours CLI."""
 
-__version__ = "0.2.1"
+__version__ = "0.2.2"

src/young_stock/methodology.py

@@ -2,7 +2,12 @@
 
 from __future__ import annotations
 
+import hashlib
+import json
+import os
 import re
+import shutil
+import tempfile
 from dataclasses import dataclass
 from pathlib import Path
 from typing import Any
@@ -15,6 +20,21 @@
     "https://raw.githubusercontent.com/AdvancingTitans/stock-analysis/main/"
     "skills/stock-analysis/SKILL.md"
 )
+STOCK_ANALYSIS_RAW_BASE = STOCK_ANALYSIS_SKILL_URL.rsplit("/", 1)[0]
+REFERENCE_PATHS = (
+    "references/output_discipline.md",
+    "references/data-source-strategy.md",
+    "references/analysis-template.md",
+    "references/methodology/m1-index-overview.md",
+    "references/methodology/m2-sector-flow.md",
+    "references/methodology/m3-upside.md",
+    "references/methodology/m4-downside.md",
+    "references/methodology/m5-style-buckets.md",
+    "references/methodology/m6-resilient.md",
+    "references/template/analysis-template.md",
+    "references/template/module-template.md",
+    "references/template/portfolio-template.md",
+)
 BUILTIN_VERSION = "4.2.0"
 BUILTIN_GUIDANCE = """stock-analysis 4.2.0:
 - 固定顺序：大盘指数概览、持仓分析、六模块深度复盘、综合持仓建议与风险提示。
@@ -37,25 +57,99 @@ def _version(text: str) -> str:
     return match.group(1) if match else BUILTIN_VERSION
 
 
+def _version_tuple(value: str) -> tuple[int, ...]:
+    parts = re.findall(r"\d+", value)
+    return tuple(int(part) for part in parts[:4]) or (0,)
+
+
 def _cache_path() -> Path:
     return young_home() / "methodologies" / "stock-analysis" / "SKILL.md"
 
 
+def _sha256(text: str) -> str:
+    return hashlib.sha256(text.encode("utf-8")).hexdigest()
+
+
+def _cached_spec(path: Path) -> tuple[str, str]:
+    if not path.exists():
+        return BUILTIN_VERSION, BUILTIN_GUIDANCE
+    skill_text = path.read_text(encoding="utf-8")
+    manifest_path = path.parent / "manifest.json"
+    if not manifest_path.exists():
+        return _version(skill_text), skill_text
+    try:
+        manifest = json.loads(manifest_path.read_text(encoding="utf-8"))
+        checksums = manifest.get("sha256") or {}
+        texts = {}
+        for relative, expected in checksums.items():
+            candidate = path.parent / relative
+            content = candidate.read_text(encoding="utf-8")
+            if _sha256(content) != expected:
+                raise ValueError("checksum mismatch")
+            texts[relative] = content
+    except (OSError, ValueError, json.JSONDecodeError):
+        return BUILTIN_VERSION, BUILTIN_GUIDANCE
+    combined = [texts.get("SKILL.md", skill_text)]
+    combined.extend(texts[relative] for relative in REFERENCE_PATHS if relative in texts)
+    return str(manifest.get("version") or _version(skill_text)), "\n\n".join(combined)
+
+
+def _download_text(client: Any, url: str, timeout: float) -> str:
+    response = client.get(url, timeout=timeout)
+    if response.status_code >= 400 or not str(response.text).strip():
+        raise RuntimeError(f"HTTP {response.status_code}")
+    return str(response.text).rstrip() + "\n"
+
+
+def _install_spec(path: Path, version: str, files: dict[str, str]) -> None:
+    parent = path.parent.parent
+    parent.mkdir(parents=True, exist_ok=True)
+    with tempfile.TemporaryDirectory(prefix="stock-analysis-", dir=parent) as temp_name:
+        temp_root = Path(temp_name)
+        for relative, content in files.items():
+            target = temp_root / relative
+            target.parent.mkdir(parents=True, exist_ok=True)
+            target.write_text(content, encoding="utf-8")
+        manifest = {
+            "version": version,
+            "sha256": {relative: _sha256(content) for relative, content in files.items()},
+        }
+        (temp_root / "manifest.json").write_text(
+            json.dumps(manifest, ensure_ascii=False, indent=2) + "\n",
+            encoding="utf-8",
+        )
+        destination = path.parent
+        backup = destination.with_name(destination.name + ".previous")
+        if backup.exists():
+            shutil.rmtree(backup)
+        if destination.exists():
+            os.replace(destination, backup)
+        os.replace(temp_root, destination)
+        if backup.exists():
+            shutil.rmtree(backup)
+
+
 def sync_stock_analysis_methodology(*, session: Any = None, timeout: float = 5) -> MethodologySpec:
     path = _cache_path()
-    current_text = path.read_text(encoding="utf-8") if path.exists() else BUILTIN_GUIDANCE
-    current_version = _version(current_text)
+    current_version, current_text = _cached_spec(path)
     client = session or requests.Session()
     try:
-        response = client.get(STOCK_ANALYSIS_SKILL_URL, timeout=timeout)
-        if response.status_code >= 400 or not str(response.text).strip():
-            raise RuntimeError(f"HTTP {response.status_code}")
-        remote_text = str(response.text)
+        remote_skill = _download_text(client, STOCK_ANALYSIS_SKILL_URL, timeout)
+    except Exception:
+        return MethodologySpec(current_version, current_text, path, updated=False)
+    remote_version = _version(remote_skill)
+    if _version_tuple(remote_version) <= _version_tuple(current_version):
+        return MethodologySpec(current_version, current_text, path, updated=False)
+    files = {"SKILL.md": remote_skill}
+    try:
+        for relative in REFERENCE_PATHS:
+            files[relative] = _download_text(
+                client,
+                f"{STOCK_ANALYSIS_RAW_BASE}/{relative}",
+                timeout,
+            )
+        _install_spec(path, remote_version, files)
     except Exception:
         return MethodologySpec(current_version, current_text, path, updated=False)
-    remote_version = _version(remote_text)
-    updated = remote_text != current_text
-    if updated:
-        path.parent.mkdir(parents=True, exist_ok=True)
-        path.write_text(remote_text.rstrip() + "\n", encoding="utf-8")
-    return MethodologySpec(remote_version, remote_text, path, updated=updated)
+    combined = [files["SKILL.md"], *(files[relative] for relative in REFERENCE_PATHS)]
+    return MethodologySpec(remote_version, "\n\n".join(combined), path, updated=True)

tests/test_methodology.py

@@ -1,21 +1,55 @@
+import json
 from types import SimpleNamespace
 
-from young_stock.methodology import sync_stock_analysis_methodology
+from young_stock.methodology import REFERENCE_PATHS, sync_stock_analysis_methodology
 
 
 class FakeSession:
+    def __init__(self, version="4.3.0"):
+        self.version = version
+        self.urls = []
+
     def get(self, url, timeout):
+        self.urls.append(url)
+        if url.endswith("SKILL.md"):
+            text = f'---\nname: stock-analysis\nmetadata:\n  version: "{self.version}"\n---\n# 新版规范\n'
+        else:
+            text = f"# {url.rsplit('/', 1)[-1]}\n\n新版模板内容\n"
         return SimpleNamespace(
             status_code=200,
-            text='---\nname: stock-analysis\nmetadata:\n  version: "4.3.0"\n---\n# 新版规范\n',
+            text=text,
         )
 
 
 def test_sync_stock_analysis_methodology_caches_new_remote_version(monkeypatch, tmp_path):
     monkeypatch.setenv("YOUNG_STOCK_HOME", str(tmp_path))
+    session = FakeSession()
 
-    result = sync_stock_analysis_methodology(session=FakeSession())
+    result = sync_stock_analysis_methodology(session=session)
 
     assert result.version == "4.3.0"
     assert result.updated is True
     assert result.path.read_text(encoding="utf-8").endswith("# 新版规范\n")
+    assert len(session.urls) == 1 + len(REFERENCE_PATHS)
+    manifest = json.loads((result.path.parent / "manifest.json").read_text(encoding="utf-8"))
+    assert manifest["version"] == "4.3.0"
+    assert set(manifest["sha256"]) == {"SKILL.md", *REFERENCE_PATHS}
+    assert "新版模板内容" in result.text
+
+
+def test_sync_does_not_replace_newer_local_version(monkeypatch, tmp_path):
+    monkeypatch.setenv("YOUNG_STOCK_HOME", str(tmp_path))
+    local = tmp_path / "methodologies" / "stock-analysis"
+    local.mkdir(parents=True)
+    (local / "SKILL.md").write_text(
+        '---\nmetadata:\n  version: "4.4.0"\n---\n# 本地新版\n',
+        encoding="utf-8",
+    )
+    session = FakeSession(version="4.3.0")
+
+    result = sync_stock_analysis_methodology(session=session)
+
+    assert result.version == "4.4.0"
+    assert result.updated is False
+    assert result.path.read_text(encoding="utf-8").endswith("# 本地新版\n")
+    assert len(session.urls) == 1

tests/test_packaging_docs.py

@@ -20,10 +20,10 @@ def test_package_version_is_next_patch_release():
     pyproject = (ROOT / "pyproject.toml").read_text(encoding="utf-8")
     init_py = (ROOT / "src" / "young_stock" / "__init__.py").read_text(encoding="utf-8")
 
-    assert 'version = "0.2.1"' in pyproject
+    assert 'version = "0.2.2"' in pyproject
     assert 'requires-python = ">=3.9"' in pyproject
     assert '"Programming Language :: Python :: 3.9"' in pyproject
-    assert '__version__ = "0.2.1"' in init_py
+    assert '__version__ = "0.2.2"' in init_py
 
 
 def test_pdf_template_is_declared_as_package_data():