flower-trellis 0.5.2-beta.1 → 0.5.2

package/enhancements/0.6/overrides/bundles/control-plane-integrity.json

@@ -5,6 +5,7 @@
   "installMode": "full-only",
   "patches": [
     "scripts/task-store-write-integrity",
-    "scripts/runtime-state-integrity"
+    "scripts/runtime-state-integrity",
+    "scripts/session-context-update-boundary"
   ]
 }

package/enhancements/0.6/overrides/conflicts.json

@@ -1101,6 +1101,28 @@
       },
       "owner": "trellis-route",
       "reason": "Claude workflow meta 必须与 shared route owner 模型一致。"
+    },
+    {
+      "id": "session-context-no-legacy-update-check",
+      "severity": "error",
+      "target": ".trellis/scripts/common/session_context.py",
+      "whenOperations": [
+        "session-context-update-imports",
+        "session-context-update-constants",
+        "session-context-update-helpers",
+        "session-context-update-output"
+      ],
+      "assertion": {
+        "type": "absent-literal",
+        "values": [
+          "def _get_update_hint(",
+          "def _mark_update_check_attempted(",
+          "def _update_marker_path(",
+          "[\"trellis\", \"--version\"]"
+        ]
+      },
+      "owner": "flower-update-hook",
+      "reason": "默认 Session Context 只负责项目上下文；更新检查必须统一由 Flower SessionStart Hook 进入。"
     }
   ]
 }

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/constants-selector.py

@@ -0,0 +1,6 @@
+_PACKAGE_NAME = "@mindfoldhq/trellis"
+_UPDATE_CHECK_TIMEOUT_SECONDS = 1.0
+_VERSION_RE = re.compile(
+    r"^\s*(\d+)(?:\.(\d+))?(?:\.(\d+))?(?:-([0-9A-Za-z.-]+))?\s*$"
+)
+_VERSION_TOKEN_RE = re.compile(r"\b\d+(?:\.\d+){1,2}(?:-[0-9A-Za-z.-]+)?\b")

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/helpers-selector.py

@@ -0,0 +1,150 @@
+def _read_project_version(repo_root: Path) -> str | None:
+    try:
+        version = (repo_root / DIR_WORKFLOW / ".version").read_text(
+            encoding="utf-8"
+        ).strip()
+    except OSError:
+        return None
+    return version or None
+
+
+def _fetch_trellis_version_output() -> str | None:
+    try:
+        result = subprocess.run(
+            ["trellis", "--version"],
+            capture_output=True,
+            text=True,
+            encoding="utf-8",
+            errors="replace",
+            timeout=_UPDATE_CHECK_TIMEOUT_SECONDS,
+        )
+    except (OSError, subprocess.SubprocessError, TimeoutError):
+        return None
+
+    if result.returncode != 0:
+        return None
+    output = f"{result.stdout}\n{result.stderr}".strip()
+    return output or None
+
+
+def _extract_available_update_version(output: str) -> str | None:
+    update_match = re.search(
+        r"Trellis update available:\s*"
+        r"(?P<current>\S+)\s*(?:→|->)\s*(?P<latest>\S+)",
+        output,
+    )
+    if update_match:
+        return update_match.group("latest").strip()
+    candidates = _VERSION_TOKEN_RE.findall(output)
+    return candidates[-1] if candidates else None
+
+
+def _resolve_available_update_version() -> str | None:
+    output = _fetch_trellis_version_output()
+    if not output:
+        return None
+    return _extract_available_update_version(output)
+
+
+def _parse_version(version: str) -> tuple[tuple[int, int, int], tuple[str, ...] | None] | None:
+    match = _VERSION_RE.match(version)
+    if not match:
+        return None
+    major, minor, patch, prerelease = match.groups()
+    numbers = (int(major), int(minor or "0"), int(patch or "0"))
+    prerelease_parts = tuple(prerelease.split(".")) if prerelease else None
+    return numbers, prerelease_parts
+
+
+def _compare_prerelease(
+    left: tuple[str, ...] | None,
+    right: tuple[str, ...] | None,
+) -> int:
+    if left is None and right is None:
+        return 0
+    if left is None:
+        return 1
+    if right is None:
+        return -1
+
+    for left_part, right_part in zip(left, right):
+        if left_part == right_part:
+            continue
+        left_numeric = left_part.isdigit()
+        right_numeric = right_part.isdigit()
+        if left_numeric and right_numeric:
+            left_int = int(left_part)
+            right_int = int(right_part)
+            return (left_int > right_int) - (left_int < right_int)
+        if left_numeric:
+            return -1
+        if right_numeric:
+            return 1
+        return (left_part > right_part) - (left_part < right_part)
+
+    return (len(left) > len(right)) - (len(left) < len(right))
+
+
+def _compare_versions(left: str, right: str) -> int | None:
+    parsed_left = _parse_version(left)
+    parsed_right = _parse_version(right)
+    if parsed_left is None or parsed_right is None:
+        return None
+
+    left_numbers, left_prerelease = parsed_left
+    right_numbers, right_prerelease = parsed_right
+    if left_numbers != right_numbers:
+        return (left_numbers > right_numbers) - (left_numbers < right_numbers)
+    return _compare_prerelease(left_prerelease, right_prerelease)
+
+
+def _update_marker_path(repo_root: Path) -> Path:
+    context_key = resolve_context_key()
+    if not context_key:
+        terminal_key = os.environ.get("TERM_SESSION_ID", "").strip()
+        context_key = terminal_key or f"ppid-{os.getppid()}"
+    safe_key = re.sub(r"[^A-Za-z0-9._-]+", "_", context_key).strip("._-")
+    if not safe_key:
+        safe_key = "session"
+    return (
+        repo_root
+        / DIR_WORKFLOW
+        / ".runtime"
+        / f"update-check-{safe_key[:160]}.marker"
+    )
+
+
+def _mark_update_check_attempted(repo_root: Path) -> bool:
+    marker_path = _update_marker_path(repo_root)
+    if marker_path.exists():
+        return False
+    try:
+        marker_path.parent.mkdir(parents=True, exist_ok=True)
+        marker_path.write_text("checked\n", encoding="utf-8")
+    except OSError:
+        pass
+    return True
+
+
+def _get_update_hint(repo_root: Path) -> str | None:
+    marker_path = _update_marker_path(repo_root)
+    if marker_path.exists():
+        return None
+
+    current_version = _read_project_version(repo_root)
+    if not current_version:
+        return None
+
+    latest_version = _resolve_available_update_version()
+    if not latest_version:
+        return None
+
+    _mark_update_check_attempted(repo_root)
+    comparison = _compare_versions(current_version, latest_version)
+    if comparison is None or comparison >= 0:
+        return None
+
+    return (
+        f"Trellis update available: {current_version} -> {latest_version}, "
+        "run trellis upgrade"
+    )

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/imports-content.py

@@ -0,0 +1,4 @@
+import json
+from pathlib import Path
+
+from .config import get_git_packages

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/imports-selector.py

@@ -0,0 +1,8 @@
+import json
+import os
+import re
+import subprocess
+from pathlib import Path
+
+from .active_task import resolve_context_key
+from .config import get_git_packages

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/output-content.py

@@ -0,0 +1,7 @@
+def output_text(repo_root: Path | None = None) -> None:
+    """Output context in text format.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    print(get_context_text(repo_root))

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/output-selector.py

@@ -0,0 +1,13 @@
+def output_text(repo_root: Path | None = None) -> None:
+    """Output context in text format.
+
+    Args:
+        repo_root: Repository root path. Defaults to auto-detected.
+    """
+    if repo_root is None:
+        repo_root = get_repo_root()
+    update_hint = _get_update_hint(repo_root)
+    if update_hint:
+        print(update_hint)
+        print("")
+    print(get_context_text(repo_root))

package/enhancements/0.6/overrides/patches/scripts/session-context-update-boundary/patch.json

@@ -0,0 +1,53 @@
+{
+  "schemaVersion": 2,
+  "id": "session-context-update-boundary",
+  "purpose": "control_plane_integrity",
+  "operations": [
+    {
+      "id": "session-context-update-imports",
+      "operation": "replace",
+      "targets": [{
+        "kind": "file",
+        "path": ".trellis/scripts/common/session_context.py",
+        "missing": "error",
+        "markerStyle": "hash"
+      }],
+      "selector": { "type": "literal", "source": "imports-selector.py" },
+      "content": { "source": "imports-content.py" }
+    },
+    {
+      "id": "session-context-update-constants",
+      "operation": "remove",
+      "targets": [{
+        "kind": "file",
+        "path": ".trellis/scripts/common/session_context.py",
+        "missing": "error",
+        "markerStyle": "hash"
+      }],
+      "selector": { "type": "literal", "source": "constants-selector.py" }
+    },
+    {
+      "id": "session-context-update-helpers",
+      "operation": "remove",
+      "targets": [{
+        "kind": "file",
+        "path": ".trellis/scripts/common/session_context.py",
+        "missing": "error",
+        "markerStyle": "hash"
+      }],
+      "selector": { "type": "literal", "source": "helpers-selector.py" }
+    },
+    {
+      "id": "session-context-update-output",
+      "operation": "replace",
+      "targets": [{
+        "kind": "file",
+        "path": ".trellis/scripts/common/session_context.py",
+        "missing": "error",
+        "markerStyle": "hash"
+      }],
+      "selector": { "type": "literal", "source": "output-selector.py" },
+      "content": { "source": "output-content.py" }
+    }
+  ]
+}

package/enhancements/MANIFEST.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-07-29T10:02:05.260Z",
+  "syncedAt": "2026-07-29T11:34:14.834Z",
   "syncedFrom": "vendor/skill-garden",
-  "sourceCommit": "1812258cdd48d99b97e8dbab41f5203134e411df",
+  "sourceCommit": "9c35c52409d53198738405861b730d942de7efb0",
   "common": {
     "codexSkills": [
       "craft-rpa",
@@ -161,6 +161,13 @@
         "scripts/runtime-state-integrity/active-task-set-content.py",
         "scripts/runtime-state-integrity/active-task-set-selector.py",
         "scripts/runtime-state-integrity/patch.json",
+        "scripts/session-context-update-boundary/constants-selector.py",
+        "scripts/session-context-update-boundary/helpers-selector.py",
+        "scripts/session-context-update-boundary/imports-content.py",
+        "scripts/session-context-update-boundary/imports-selector.py",
+        "scripts/session-context-update-boundary/output-content.py",
+        "scripts/session-context-update-boundary/output-selector.py",
+        "scripts/session-context-update-boundary/patch.json",
         "scripts/task-start-brief-gate/degraded-content.py",
         "scripts/task-start-brief-gate/degraded-selector.py",
         "scripts/task-start-brief-gate/guard-content.py",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flower-trellis",
-  "version": "0.5.2-beta.1",
+  "version": "0.5.2",
   "description": "一键安装/升级 Trellis 并自动融合 skill-garden 强化包(默认 Claude + agents)",
   "type": "module",
   "bin": {
@@ -68,9 +68,9 @@
     "commit-and-tag-version": "^12.7.3"
   },
   "flowerReleaseNotes": {
-    "version": "0.5.2-beta.1",
+    "version": "0.5.2",
     "source": "CHANGELOG.md",
-    "body": "### ✨ 新功能 Features\n\n* **0.6:** 同步 Push 门禁与意图识别 ([8abf3b1](https://github.com/SilentFlower/flower-trellis/commit/8abf3b1439d7a5dd2af0d698c4094aa6c7207fb3))\n* **brief:** 同步 Brief 显式预授权流程 ([7c179af](https://github.com/SilentFlower/flower-trellis/commit/7c179affd7389cac053d28104e0d624773159c72))\n* **spec-router:** 同步章节感知加载能力 ([0d51a24](https://github.com/SilentFlower/flower-trellis/commit/0d51a24e6136bb9b167cd5716eeb9958b5d8412e))\n* **trellis:** 补全 Meta 架构并修复 Auto-Loop 自恢复 ([943179f](https://github.com/SilentFlower/flower-trellis/commit/943179f42e3e3d068bf98f8ff60b2aa324acc4dd))\n\n\n### 🐛 修复 Bug Fixes\n\n* **trellis:** 移除旧更新检查 marker ([a33f376](https://github.com/SilentFlower/flower-trellis/commit/a33f376d7efe15441cba8fbe0b0a67c6f1a15f6c))",
+    "body": "### ✨ 新功能 Features\n\n* **0.6:** 同步 Push 门禁与意图识别 ([8abf3b1](https://github.com/SilentFlower/flower-trellis/commit/8abf3b1439d7a5dd2af0d698c4094aa6c7207fb3))\n* **brief:** 同步 Brief 显式预授权流程 ([7c179af](https://github.com/SilentFlower/flower-trellis/commit/7c179affd7389cac053d28104e0d624773159c72))\n* **spec-router:** 同步章节感知加载能力 ([0d51a24](https://github.com/SilentFlower/flower-trellis/commit/0d51a24e6136bb9b167cd5716eeb9958b5d8412e))\n* **trellis:** 补全 Meta 架构并修复 Auto-Loop 自恢复 ([943179f](https://github.com/SilentFlower/flower-trellis/commit/943179f42e3e3d068bf98f8ff60b2aa324acc4dd))\n* **plugin:** 建立契约与项目状态存储 ([3c664c3](https://github.com/SilentFlower/flower-trellis/commit/3c664c337806849d7bf040f269eb0f1ebed115f0))\n* **plugin:** 支持 GitHub 外部格式与交互来源管理 ([8701039](https://github.com/SilentFlower/flower-trellis/commit/8701039ea8f8018e7e8d017c0ac5f545b9b2549b))\n* **plugin:** 新增 GitLab 市场外部来源 ([3688744](https://github.com/SilentFlower/flower-trellis/commit/3688744d7663952d437f4bc4e5c8187798c45453))\n* **plugin:** 新增插件能力授权策略 ([32ec993](https://github.com/SilentFlower/flower-trellis/commit/32ec993de77686fb411451c4165ca17367cf5e33))\n* **plugin:** 新增插件运行时生命周期 ([0d7c5b1](https://github.com/SilentFlower/flower-trellis/commit/0d7c5b1ae4821e8cbadcd857608399c2e725c560))\n* **plugin:** 添加作者工具与 CI 契约 ([4e34b87](https://github.com/SilentFlower/flower-trellis/commit/4e34b878f37fddb3732b2264b90f79b3610c82d0))\n* **plugin:** 迁移 skill-garden 到插件运行时 ([2e9fd18](https://github.com/SilentFlower/flower-trellis/commit/2e9fd18123e3164a68971725269619401b2625b4))\n* 增加 Check-All 下一步引导 ([fa488f8](https://github.com/SilentFlower/flower-trellis/commit/fa488f83c85983b8b8c545b85e4e42d20b290bdf))\n\n\n### 🐛 修复 Bug Fixes\n\n* **trellis:** 移除旧更新检查 marker ([a33f376](https://github.com/SilentFlower/flower-trellis/commit/a33f376d7efe15441cba8fbe0b0a67c6f1a15f6c))\n* **plugin:** 优化外部来源交互与 archive 安全检测 ([4699a22](https://github.com/SilentFlower/flower-trellis/commit/4699a2211cb280e5a085c852950fda52af28c456))\n* **plugin:** 修复远程更新并完成集成验收 ([3db8320](https://github.com/SilentFlower/flower-trellis/commit/3db83208a6da12c3bbcad1730e144271ff02a96a))\n* **trellis:** 优化 auto-loop 重试预算与跟踪状态 ([19d7a1a](https://github.com/SilentFlower/flower-trellis/commit/19d7a1ae5302af56085e1053706442ad7cb347b0))\n* **trellis:** 支持跳过 Check-All 并修复 update -y ([1bd0a12](https://github.com/SilentFlower/flower-trellis/commit/1bd0a126f91f6b915d2253f1a497bda40fc41edb))\n* 修复 Windows Trellis Patch 命令漂移 ([5892e7f](https://github.com/SilentFlower/flower-trellis/commit/5892e7f7629be0a7ee075a3758f594a220c7db1f))\n\n\n### ♻️ 重构 Refactor\n\n* **trellis:** 拆分 Check-All 检查档位并同步快照 ([ef1a8c4](https://github.com/SilentFlower/flower-trellis/commit/ef1a8c434244c06cf565c449173c6d6763a0a160))\n\n\n### 🧰 维护 Maintenance\n\n* **trellis:** 同步 Flower 0.5.1-beta.1 清单 ([d3dfc27](https://github.com/SilentFlower/flower-trellis/commit/d3dfc2759927b0759b10e2ae246b68438dc3d339))\n* **trellis:** 执行 Flower 自更新同步 ([f79ce33](https://github.com/SilentFlower/flower-trellis/commit/f79ce33bcc409129a054f1b59a016cdbe1ea991b))",
     "truncated": false
   },
   "optionalDependencies": {

package/src/builtin-plugins/skill-garden/content-adapter.js

@@ -20,6 +20,7 @@ import { PKG_ROOT } from "../../lib/paths.js";
 import { injectWorkflow } from "../../lib/workflow-inject.js";
 import { applyCodexTweaks } from "../../lib/codex-tweaks.js";
 import { applyClaudeTweaks } from "../../lib/claude-tweaks.js";
+import { materializeTrellisPythonText } from "../../lib/trellis-python-command.js";
 import { describeInstalledCommonSkillSync } from "../../lib/skill-catalog.js";
 import {
   PLUGIN_RUNTIME_ERROR_CODES,
@@ -46,6 +47,7 @@ const SCRIPT_ALIASES = Object.freeze({
     "intent-routing", "auto-loop", "auto-loop-runner", "trellis-auto-loop",
   ],
 });
+const TRELLIS_TEXT_EXTENSIONS = new Set([".json", ".md", ".toml", ".txt", ".yaml", ".yml"]);
 
 /**
  * 列出目标目录中的普通文件。
@@ -66,7 +68,7 @@ function listExistingFiles(directory) {
  */
 export function projectSkillGardenContent(options) {
   const { projectRoot, resolved, pluginPackage } = options;
-  const { variantDir, skills } = pluginPackage.skillGarden;
+  const { variantDir, skills, pythonCommand } = pluginPackage.skillGarden;
   const payloads = new Map();
   const mutations = [];
   const directoryRemovals = [];
@@ -86,20 +88,24 @@ export function projectSkillGardenContent(options) {
    * @param {Buffer} content 最终字节
    * @param {string} source 来源说明
    * @param {"exclusive"|"shared"} ownership 所有权
+   * @param {boolean} materializePython 是否按目标项目命令物化明确文本载荷
    */
-  function addFile(target, content, source, ownership = "exclusive") {
+  function addFile(target, content, source, ownership = "exclusive", materializePython = false) {
     assertSafePosixRelativePath(target, "skill-garden 投影目标");
     const absoluteTarget = path.join(projectRoot, ...target.split("/"));
+    const payload = materializePython && TRELLIS_TEXT_EXTENSIONS.has(path.extname(target))
+      ? Buffer.from(materializeTrellisPythonText(content.toString("utf8"), pythonCommand))
+      : content;
     const mutation = {
       owner: resolved.id,
       target,
       operation: "write",
       beforeHash: hashFileIfExists(absoluteTarget),
-      afterHash: hashContent(content),
+      afterHash: hashContent(payload),
       source,
       allowUnownedWrite: true,
     };
-    payloads.set(contentMutationKey(mutation), content);
+    payloads.set(contentMutationKey(mutation), payload);
     mutations.push(mutation);
     paths.set(target, {
       path: target,
@@ -116,13 +122,26 @@ export function projectSkillGardenContent(options) {
    * @param {string} targetRoot 目标目录
    * @param {string} sourceLabel 来源标签
    * @param {"exclusive"|"shared"} ownership 所有权
+   * @param {boolean} materializePython 是否按目标项目命令物化明确文本载荷
    */
-  function addTree(sourceRoot, targetRoot, sourceLabel, ownership = "exclusive") {
+  function addTree(
+    sourceRoot,
+    targetRoot,
+    sourceLabel,
+    ownership = "exclusive",
+    materializePython = false,
+  ) {
     const desired = new Set();
     for (const file of listCanonicalTreeFiles(sourceRoot)) {
       const target = `${targetRoot}/${file.path}`;
       desired.add(file.path);
-      addFile(target, fs.readFileSync(file.absolutePath), `${sourceLabel}:${file.path}`, ownership);
+      addFile(
+        target,
+        fs.readFileSync(file.absolutePath),
+        `${sourceLabel}:${file.path}`,
+        ownership,
+        materializePython,
+      );
     }
     for (const file of listExistingFiles(path.join(projectRoot, ...targetRoot.split("/")))) {
       if (desired.has(file.path)) continue;
@@ -192,6 +211,8 @@ export function projectSkillGardenContent(options) {
         path.join(sourceRoot, entry.name),
         `${target.root}/${entry.name}`,
         `skill-garden:${pluginPackage.skillGarden.variant}:${target.source}:${entry.name}`,
+        "exclusive",
+        pluginPackage.skillGarden.variant === "0.6",
       );
       installed.add(entry.name);
     }
@@ -208,6 +229,8 @@ export function projectSkillGardenContent(options) {
         `.claude/commands/trellis/${file.name}`,
         fs.readFileSync(path.join(commandRoot, file.name)),
         `skill-garden:${pluginPackage.skillGarden.variant}:command:${file.name}`,
+        "exclusive",
+        pluginPackage.skillGarden.variant === "0.6",
       );
       installed.add(name);
     }

package/src/builtin-plugins/skill-garden/provider.js

@@ -9,6 +9,7 @@ import { validatePluginManifest } from "../../plugin/schemas/plugin-manifest.js"
 import { markRuntimeBuiltinProvider } from "../../plugin/runtime-extensions.js";
 import { BuiltinSourceProvider } from "../../plugin/sources/builtin-provider.js";
 import { flowerPatchAdapters } from "../../lib/platform-patch-adapters.js";
+import { resolveTrellisPythonCommand } from "../../lib/trellis-python-command.js";
 import { projectSkillGardenContent } from "./content-adapter.js";
 
 /** 内置 skill-garden canonical Plugin ID。 */
@@ -97,6 +98,7 @@ function runtimeManifest(variant) {
  */
 function ensureSkillGardenReady(provider) {
   if (provider.snapshot) return;
+  provider.pythonCommand = resolveTrellisPythonCommand(provider.projectRoot);
   provider.snapshot = resolveEnhancementSnapshot(provider.projectRoot, provider.variantOverride);
   provider.manifest = runtimeManifest(provider.snapshot.variant);
   provider.integrity = stablePayloadDigest([
@@ -145,6 +147,7 @@ export class SkillGardenBuiltinProvider {
     this.manifest = null;
     this.integrity = null;
     this.resolutionManifest = null;
+    this.pythonCommand = null;
     if (fs.existsSync(path.join(this.projectRoot, ".trellis", ".version"))) ensureSkillGardenReady(this);
     markRuntimeBuiltinProvider(this);
   }
@@ -208,11 +211,13 @@ export class SkillGardenBuiltinProvider {
           compatibilityFile: path.join(this.snapshot.variantDir, "overrides", "compatibility.json"),
           conflictsFile: path.join(this.snapshot.variantDir, "overrides", "conflicts.json"),
         },
+        textMaterialization: { trellisPythonCommand: this.pythonCommand.command },
       },
       {
         id: "flower",
         patchesDir: path.join(PKG_ROOT, "src", "patches", "platforms"),
         bundlesDir: path.join(PKG_ROOT, "src", "patches", "bundles"),
+        textMaterialization: { trellisPythonCommand: this.pythonCommand.command },
       },
     ] : [];
     return {
@@ -220,10 +225,16 @@ export class SkillGardenBuiltinProvider {
       manifest: this.resolutionManifest,
       integrity: acceptedIntegrity,
       catalogs,
-      systemAdapters: this.snapshot.variant === "0.6" ? flowerPatchAdapters() : {},
+      systemAdapters: this.snapshot.variant === "0.6"
+        ? flowerPatchAdapters(this.pythonCommand.command)
+        : {},
       patchOptions: { skills: this.skills },
       allowContentPatchOverlap: true,
-      skillGarden: { ...this.snapshot, skills: this.skills },
+      skillGarden: {
+        ...this.snapshot,
+        skills: this.skills,
+        pythonCommand: this.pythonCommand.command,
+      },
     };
   }
 

package/src/lib/patch-conflicts.js

@@ -1,6 +1,7 @@
 import fs from "node:fs";
 import path from "node:path";
 import { resolvePatchCatalogPolicy } from "./patch-engine.js";
+import { materializeTrellisPythonText } from "./trellis-python-command.js";
 
 const SEVERITIES = new Set(["error", "warning", "info"]);
 const ID_RE = /^[a-z0-9]+(?:-[a-z0-9]+)*$/;
@@ -155,6 +156,27 @@ function validateConflicts(raw) {
   return raw;
 }
 
+function materializeConflictAssertions(conflicts, command) {
+  if (command === undefined) return conflicts;
+  return {
+    ...conflicts,
+    rules: conflicts.rules.map((rule) => ({
+      ...rule,
+      assertion: rule.assertion.type === "max-occurrences"
+        ? {
+          ...rule.assertion,
+          value: materializeTrellisPythonText(rule.assertion.value, command),
+        }
+        : {
+          ...rule.assertion,
+          values: rule.assertion.values.map((value) =>
+            materializeTrellisPythonText(value, command)
+          ),
+        },
+    })),
+  };
+}
+
 function parseVersion(value) {
   if (typeof value !== "string") return null;
   const match = value.match(SEMVER_RE);
@@ -253,7 +275,7 @@ export function loadPatchPolicy(overridesDir, catalogId = "skill-garden") {
 /**
  * 按 catalog descriptor 加载并校验其声明式 Patch policy。
  *
- * @param {Array<{id:string,policy?:{compatibilityFile?:string,conflictsFile?:string}}>} catalogs catalog 描述符
+ * @param {Array<{id:string,policy?:{compatibilityFile?:string,conflictsFile?:string},textMaterialization?:{trellisPythonCommand:string}}>} catalogs catalog 描述符
  * @returns {Array<{catalog:string,compatibility?:object,conflicts?:object}>} 已校验的 policy 列表
  */
 export function loadPatchPolicies(catalogs) {
@@ -271,10 +293,14 @@ export function loadPatchPolicies(catalogs) {
         ));
       }
       if (paths.conflictsFile) {
-        policy.conflicts = validateConflicts(readJson(
+        const conflicts = validateConflicts(readJson(
           paths.conflictsFile,
           `${catalogId} conflict policy`,
         ));
+        policy.conflicts = materializeConflictAssertions(
+          conflicts,
+          catalog.textMaterialization?.trellisPythonCommand,
+        );
       }
       if (!policy.compatibility && !policy.conflicts) {
         throw new Error(`catalog ${catalogId} policy 至少声明一个文件`);

package/src/lib/patch-engine.js

@@ -3,6 +3,7 @@ import fs from "node:fs";
 import path from "node:path";
 import { preserveFirstBackup } from "./backup.js";
 import { shouldInstallName } from "./skill-filter.js";
+import { materializeTrellisPythonText } from "./trellis-python-command.js";
 
 const PATCH_SCHEMA_VERSION = 2;
 const BUNDLE_SCHEMA_VERSION = 1;
@@ -691,9 +692,45 @@ function resolveCatalogPolicy(catalog, catalogFiles) {
   return policy;
 }
 
+function resolveCatalogPythonCommand(catalog) {
+  if (catalog.textMaterialization === undefined) return null;
+  assertPlainObject(catalog.textMaterialization, `catalog ${catalog.id} textMaterialization`);
+  const keys = Object.keys(catalog.textMaterialization);
+  if (keys.length !== 1 || keys[0] !== "trellisPythonCommand") {
+    throw new Error(`catalog ${catalog.id} textMaterialization 只支持 trellisPythonCommand`);
+  }
+  const command = catalog.textMaterialization.trellisPythonCommand;
+  if (typeof command !== "string" || !command.trim()) {
+    throw new Error(`catalog ${catalog.id} textMaterialization.trellisPythonCommand 必须是非空字符串`);
+  }
+  return command;
+}
+
+function materializeOperationPythonCommand(operation, command) {
+  if (!command) return operation;
+  const selectorText = typeof operation.selectorText === "string"
+    ? materializeTrellisPythonText(operation.selectorText, command)
+    : operation.selectorText;
+  return {
+    ...operation,
+    selector: {
+      ...operation.selector,
+      ...(typeof operation.selector.text === "string" ? { text: selectorText } : {}),
+    },
+    selectorText,
+    content: typeof operation.content === "string"
+      ? materializeTrellisPythonText(operation.content, command)
+      : operation.content,
+    baselines: operation.baselines.map((baseline) =>
+      materializeTrellisPythonText(baseline, command)
+    ),
+  };
+}
+
 function loadCatalog(catalog, skills, allowedSelectors) {
   assertPlainObject(catalog, "Patch catalog");
   assertId(catalog.id, "Patch catalog.id");
+  const pythonCommand = resolveCatalogPythonCommand(catalog);
   const patchesDir = path.resolve(catalog.patchesDir);
   const bundlesDir = path.resolve(catalog.bundlesDir);
   const catalogRoot = path.dirname(patchesDir);
@@ -742,9 +779,10 @@ function loadCatalog(catalog, skills, allowedSelectors) {
       qualifiedId: qualifyId(catalog.id, raw.id),
       markerIdentity,
     };
-    patch.operations = raw.operations.map((operation) =>
-      normalizeOperation(operation, leafDir, patch, seenOperationIds, allowedSelectors)
-    );
+    patch.operations = raw.operations.map((operation) => materializeOperationPythonCommand(
+      normalizeOperation(operation, leafDir, patch, seenOperationIds, allowedSelectors),
+      pythonCommand,
+    ));
     patchByRef.set(ref, patch);
     catalogFiles.push(file, ...listRecursive(leafDir, (candidate) => candidate !== file));
   }

package/src/lib/platform-patch-adapters.js

@@ -25,9 +25,9 @@ function findHookCommand(config, event, needle) {
   return null;
 }
 
-function resolveCommand(name, config) {
+function resolveCommand(name, config, pythonCommand) {
   const codexBase = findHookCommand(config, "UserPromptSubmit", CODEX_WORKFLOW_HOOK) ||
-    `python3 -X utf8 ${CODEX_WORKFLOW_HOOK}`;
+    `${pythonCommand} -X utf8 ${CODEX_WORKFLOW_HOOK}`;
   if (name === "codex-session-start") {
     return codexBase.replace(CODEX_WORKFLOW_HOOK, CODEX_SESSION_START);
   }
@@ -35,14 +35,14 @@ function resolveCommand(name, config) {
     return codexBase.replace(CODEX_WORKFLOW_HOOK, FLOWER_UPDATE_HOOK_REL);
   }
   const claudeBase = findHookCommand(config, "UserPromptSubmit", CLAUDE_WORKFLOW_HOOK) ||
-    `python3 ${CLAUDE_WORKFLOW_HOOK}`;
+    `${pythonCommand} ${CLAUDE_WORKFLOW_HOOK}`;
   if (name === "claude-flower-update") {
     return claudeBase.replace(CLAUDE_WORKFLOW_HOOK, FLOWER_UPDATE_HOOK_REL);
   }
   throw new Error(`未知 Hook commandResolver:${name}`);
 }
 
-function applyJsonHookCommand({ value, operation }) {
+function applyJsonHookCommand({ value, operation, pythonCommand = "python3" }) {
   let config;
   try {
     config = value.trim() ? JSON.parse(value) : {};
@@ -86,7 +86,7 @@ function applyJsonHookCommand({ value, operation }) {
     }
     let command;
     try {
-      command = resolveCommand(content.commandResolver, config);
+      command = resolveCommand(content.commandResolver, config, pythonCommand);
     } catch (error) {
       return { error: error.message };
     }
@@ -304,11 +304,12 @@ function applyTomlSection({ value, operation }) {
 /**
  * Flower 自有 Patch Adapter 注册表。
  *
+ * @param {string} [pythonCommand] 目标 Trellis 项目实际使用的 Python 命令
  * @returns {Record<string, Function>} selector type 到受控 Adapter 的映射
  */
-export function flowerPatchAdapters() {
+export function flowerPatchAdapters(pythonCommand = "python3") {
   return {
-    "json-hook-command": applyJsonHookCommand,
+    "json-hook-command": (context) => applyJsonHookCommand({ ...context, pythonCommand }),
     "yaml-key": applyYamlKey,
     "toml-section": applyTomlSection,
   };

package/src/lib/trellis-python-command.js

@@ -0,0 +1,95 @@
+import fs from "node:fs";
+import path from "node:path";
+
+const TARGET_EVIDENCE_FILES = Object.freeze([
+  ".codex/hooks.json",
+  ".claude/settings.json",
+  ".trellis/workflow.md",
+]);
+const GENERATED_COMMAND_RE = /(?:^|[\s`"'([{])(py -3|python3|python)(?=\s+(?:-X\s+utf8\s+)?(?:\.\/)?(?:\.trellis\/scripts|\.codex\/hooks|\.claude\/hooks)\/)/m;
+
+/**
+ * 校验可用于 Trellis 文本物化的 Python 命令。
+ *
+ * @param {unknown} value 待校验命令
+ * @param {string} label 错误字段说明
+ * @returns {string} 去除首尾空白后的命令
+ */
+function normalizePythonCommand(value, label) {
+  if (typeof value !== "string" || !value.trim()) {
+    throw new Error(`${label} 必须是非空字符串`);
+  }
+  const command = value.trim();
+  if (command.includes("\0") || /[\r\n]/.test(command)) {
+    throw new Error(`${label} 不能包含换行或 NUL`);
+  }
+  return command;
+}
+
+/**
+ * 从 Trellis 已生成文件中识别实际使用的 Python 命令。
+ *
+ * @param {string} targetRoot 目标项目根目录
+ * @returns {{command:string,source:string}|null} 命令及证据来源；没有证据时返回 null
+ */
+function resolveGeneratedCommand(targetRoot) {
+  for (const relative of TARGET_EVIDENCE_FILES) {
+    const file = path.join(targetRoot, ...relative.split("/"));
+    if (!fs.existsSync(file) || !fs.statSync(file).isFile()) continue;
+    let value;
+    try {
+      value = fs.readFileSync(file, "utf8");
+    } catch {
+      continue;
+    }
+    const match = value.match(GENERATED_COMMAND_RE);
+    if (match) return { command: match[1], source: relative };
+  }
+  return null;
+}
+
+/**
+ * 解析目标 Trellis 项目实际使用的 Python 命令。
+ *
+ * 已生成目标文件是最高优先级证据；仅在目标中没有证据时才读取环境变量和平台回退。
+ *
+ * @param {string} target 目标 Trellis 项目根目录
+ * @param {{env?:Record<string,string|undefined>,platform?:string}} [options] 环境与平台覆盖，主要用于测试
+ * @returns {{command:string,source:string}} 命令及解析来源
+ */
+export function resolveTrellisPythonCommand(target, options = {}) {
+  const targetRoot = path.resolve(target);
+  const generated = resolveGeneratedCommand(targetRoot);
+  if (generated) return generated;
+
+  const env = options.env || process.env;
+  if (env.TRELLIS_PYTHON_CMD !== undefined) {
+    return {
+      command: normalizePythonCommand(env.TRELLIS_PYTHON_CMD, "TRELLIS_PYTHON_CMD"),
+      source: "env:TRELLIS_PYTHON_CMD",
+    };
+  }
+
+  const platform = options.platform || process.platform;
+  return {
+    command: platform === "win32" ? "python" : "python3",
+    source: `platform:${platform}`,
+  };
+}
+
+/**
+ * 按 Trellis 模板渲染规则物化文本中的 canonical `python3` 命令。
+ *
+ * @param {string} value canonical Trellis 文本
+ * @param {string} command 目标项目 Python 命令
+ * @returns {string} 已物化文本
+ */
+export function materializeTrellisPythonText(value, command) {
+  if (typeof value !== "string") throw new Error("Trellis Python 文本必须是字符串");
+  const normalizedCommand = normalizePythonCommand(command, "Trellis Python 命令");
+  if (normalizedCommand === "python3") return value;
+  return value
+    .split("\n")
+    .map((line) => line.startsWith("#!") ? line : line.replaceAll("python3", normalizedCommand))
+    .join("\n");
+}