flower-trellis 0.6.5 → 0.6.7

package/enhancements/0.6/scripts/worktree_setup.py

@@ -35,7 +35,7 @@ ROUTE_PREFERENCE_MODES = {
 NOT_INHERITED_LOCAL_STATE = (
     "session-state",
     "auto-loop",
-    "flower-local-state",
+    "flower-control-state",
     "platform-local-settings",
     "cache-and-transaction-state",
 )
@@ -496,6 +496,60 @@ def _registry_registration_conflicts(
     return conflicts
 
 
+def _flower_call(operation: str, **values: Any) -> dict[str, Any]:
+    """调用 Flower 随包适配器，保持 Plugin schema 和写入逻辑的单一归属。"""
+    executable = os.environ.get("FLOWER_WORKTREE_NODE")
+    helper = os.environ.get("FLOWER_WORKTREE_HELPER")
+    if not executable or not helper:
+        if operation == "status":
+            return {"installation": "unchecked", "version": None, "source": None, "reason": "flower-cli-required"}
+        source = Path(values.get("source", "."))
+        flower_directory = source / ".flower"
+        if operation == "plan" and not flower_directory.is_symlink() and not any(
+            (flower_directory / name).exists() for name in ("plugins.json", "plugin-lock.json", "state.json")
+        ):
+            return {"action": "unavailable", "paths": [], "reason": "source-installation-missing"}
+        raise WorktreeSetupError("flower-cli-required", "Flower 继承需要通过外部 flower-trellis worktree 命令执行")
+    try:
+        result = subprocess.run(
+            [executable, helper],
+            input=json.dumps({"operation": operation, **values}, ensure_ascii=False),
+            capture_output=True,
+            text=True,
+            timeout=60,
+            check=False,
+        )
+        payload = json.loads(result.stdout)
+    except (OSError, subprocess.SubprocessError, ValueError) as error:
+        raise WorktreeSetupError("flower-adapter-failed", "Flower worktree 适配器执行失败", error=str(error)) from error
+    if not isinstance(payload, dict) or payload.get("ok") is not True or result.returncode != 0:
+        details = payload if isinstance(payload, dict) else {}
+        raise WorktreeSetupError(
+            details.get("reason", "flower-adapter-failed"),
+            details.get("message", "Flower worktree 适配器返回非法结果"),
+            path=details.get("path"),
+        )
+    if not isinstance(payload.get("result"), dict):
+        raise WorktreeSetupError("flower-adapter-failed", "Flower worktree 适配器缺少结构化结果")
+    value = payload["result"]
+    if operation == "status":
+        valid = value.get("installation") in {"complete", "incomplete", "invalid"}
+    elif operation in {"plan", "apply"}:
+        valid = (
+            value.get("action") in {"inherited", "preserved", "unavailable"}
+            and isinstance(value.get("paths"), list)
+            and all(isinstance(item, str) for item in value["paths"])
+            and isinstance(value.get("digest"), str)
+            and value["digest"].startswith("sha256:")
+            and len(value["digest"]) == 71
+        )
+    else:
+        valid = value.get("action") == "rolledBack"
+    if not valid:
+        raise WorktreeSetupError("flower-adapter-failed", "Flower worktree 适配器结果不符合操作契约")
+    return value
+
+
 def _analyze(target_arg: str | None) -> dict[str, Any]:
     """生成 target-local readiness 诊断，且不写盘。"""
     context = _worktree_context(_resolve_start(target_arg))
@@ -537,7 +591,7 @@ def _analyze(target_arg: str | None) -> dict[str, Any]:
             conflicts.append({"path": relative, "reason": item["reason"]})
         else:
             item["state"] = "missing"
-            if relative in configured:
+            if relative in configured and relative != ".flower":
                 missing_configured.append(relative)
         entries.append(item)
 
@@ -610,11 +664,14 @@ def _analyze(target_arg: str | None) -> dict[str, Any]:
         },
         "actions": actions,
         "conflicts": conflicts,
+        "flower": _flower_call("status", target=str(target_root)),
     }
 
 
 def _developer_from_file(target_root: Path) -> str | None:
     """从目标本地 `.developer` 读取开发者名。"""
+    if (target_root / ".trellis").is_symlink() or (target_root / ".trellis/.developer").is_symlink():
+        return None
     try:
         lines = (target_root / ".trellis/.developer").read_text(encoding="utf-8").splitlines()
     except OSError:
@@ -721,6 +778,7 @@ def _prepare_local(
     *,
     source: str | None = None,
     inherit_route_prefs: bool = False,
+    inherit_flower: bool = False,
 ) -> dict[str, Any]:
     """初始化当前 worktree 自己的 gitignored 运行态并注册。"""
     if plan["status"] == "needs-migration":
@@ -734,22 +792,23 @@ def _prepare_local(
     context = _worktree_context(target_root)
     source_context = None
     source_developer = None
-    if inherit_route_prefs:
+    if inherit_route_prefs or inherit_flower:
         if not source:
             raise WorktreeSetupError(
                 "route-preferences-source-required",
-                "显式继承 route 偏好时需要 --source",
+                "显式继承本地信息时需要 --source",
             )
         source_context = _worktree_context(_resolve_start(source))
         if source_context["gitCommonDir"] != context["gitCommonDir"]:
             raise WorktreeSetupError(
                 "route-preferences-repository-mismatch",
-                "route 偏好来源与目标不属于同一 Git 仓库",
+                "继承来源与目标不属于同一 Git 仓库",
             )
         source_developer = _developer_from_file(source_context["targetRoot"])
     changed_paths: list[str] = []
     route_transfer = {"action": "notRequested", "values": {}}
-    with _registry_lock(context["gitCommonDir"]):
+    flower_transfer: dict[str, Any] = {"action": "notRequested", "paths": []}
+    with _registry_lock(context["gitCommonDir"]), tempfile.TemporaryDirectory(prefix="flower-worktree-") as temporary:
         current_developer = _developer_from_file(target_root)
         registry = _load_registry(context["gitCommonDir"])
         registration_conflicts = _registry_registration_conflicts(context, registry, task=None)
@@ -781,17 +840,42 @@ def _prepare_local(
                 source_developer,
                 normalized_developer,
             )
-        runtime_sessions = target_root / ".trellis/.runtime/sessions"
-        if not runtime_sessions.is_dir():
-            runtime_sessions.mkdir(parents=True, exist_ok=True)
-            changed_paths.append(".trellis/.runtime/sessions")
-        if current_developer is None:
-            _write_developer(target_root, normalized_developer)
-            changed_paths.append(".trellis/.developer")
-        if route_transfer["action"] == "inherited":
-            _write_route_preferences(target_root, route_transfer["values"])
-            changed_paths.append(ROUTE_PREFERENCES_PATH)
-        registry_changed = _register_worktree(context, developer=normalized_developer)
+        journal = str(Path(temporary) / "flower-receipt.json")
+        try:
+            if inherit_flower:
+                flower_input = {
+                    "source": str(source_context["targetRoot"]),
+                    "target": str(target_root),
+                    "sourceDeveloper": source_developer,
+                    "targetDeveloper": normalized_developer,
+                }
+                flower_transfer = _flower_call("plan", **flower_input)
+                flower_transfer = _flower_call(
+                    "apply", **flower_input, expectedDigest=flower_transfer.get("digest"), journal=journal,
+                )
+                flower_transfer.pop("receipt", None)
+                changed_paths.extend(flower_transfer.get("paths", []))
+            runtime_sessions = target_root / ".trellis/.runtime/sessions"
+            if not runtime_sessions.is_dir():
+                runtime_sessions.mkdir(parents=True, exist_ok=True)
+                changed_paths.append(".trellis/.runtime/sessions")
+            if current_developer is None:
+                _write_developer(target_root, normalized_developer)
+                changed_paths.append(".trellis/.developer")
+            if route_transfer["action"] == "inherited":
+                _write_route_preferences(target_root, route_transfer["values"])
+                changed_paths.append(ROUTE_PREFERENCES_PATH)
+            registry_changed = _register_worktree(context, developer=normalized_developer)
+        except Exception as error:
+            if Path(journal).is_file():
+                try:
+                    _flower_call("rollback", target=str(target_root), journal=journal)
+                except WorktreeSetupError as rollback_error:
+                    raise WorktreeSetupError(
+                        "flower-rollback-failed", "prepare 失败且 Flower 记录回滚不完整",
+                        error=str(error), rollbackError=str(rollback_error),
+                    ) from error
+            raise
     result = {
         **_analyze(str(target_root)),
         "status": "prepared" if changed_paths or registry_changed else "ready-local",
@@ -801,6 +885,7 @@ def _prepare_local(
     }
     result["localStateTransfer"] = {
         "routePreferences": route_transfer,
+        "flower": flower_transfer,
         "notInherited": list(NOT_INHERITED_LOCAL_STATE),
     }
     return result
@@ -1121,6 +1206,10 @@ def _create_plan(args: argparse.Namespace) -> dict[str, Any]:
     if not developer:
         raise WorktreeSetupError("developer-required", "create 需要 --developer 或来源 worktree 的本地身份")
     route_transfer = _route_preference_transfer(source_root, target, source_developer, developer)
+    flower_transfer = _flower_call(
+        "plan", source=str(source_root), target=str(target), baseCommit=resolved_commit,
+        sourceDeveloper=source_developer, targetDeveloper=developer,
+    )
     plan: dict[str, Any] = {
         "status": "confirmation-required",
         "changed": False,
@@ -1161,6 +1250,7 @@ def _create_plan(args: argparse.Namespace) -> dict[str, Any]:
                 "sourceName": source_developer,
             },
             "routePreferences": route_transfer,
+            "flower": flower_transfer,
             "initialized": ["session-runtime"],
             "notInherited": list(NOT_INHERITED_LOCAL_STATE),
         },
@@ -1239,6 +1329,16 @@ def _create(args: argparse.Namespace) -> dict[str, Any]:
             if route_transfer["action"] == "inherited":
                 _write_route_preferences(target, route_transfer["values"])
 
+            flower_transfer = plan["localStateTransfer"]["flower"]
+            if flower_transfer.get("digest"):
+                flower_transfer = _flower_call(
+                    "apply", source=str(source_root), target=str(target), baseCommit=base_commit,
+                    sourceDeveloper=plan["localStateTransfer"]["developer"]["sourceName"],
+                    targetDeveloper=developer, expectedDigest=flower_transfer["digest"],
+                )
+                flower_transfer.pop("receipt", None)
+                plan["localStateTransfer"]["flower"] = flower_transfer
+
             task_script = target / ".trellis/scripts/task.py"
             if not task_script.is_file():
                 raise WorktreeSetupError("task-script-missing", "目标分支缺少 `.trellis/scripts/task.py`")
@@ -1561,6 +1661,7 @@ def build_parser() -> argparse.ArgumentParser:
                 action="store_true",
                 help="inherit normalized route preferences from --source",
             )
+            command_parser.add_argument("--inherit-flower", action="store_true", help="inherit verified Flower records from --source")
         if command == "migrate":
             command_parser.add_argument("--dry-run", action="store_true", help="validate migration without writing")
 
@@ -1603,6 +1704,7 @@ def main(argv: list[str] | None = None) -> int:
                     args.developer,
                     source=args.source,
                     inherit_route_prefs=args.inherit_route_prefs,
+                    inherit_flower=args.inherit_flower,
                 )
             elif args.command == "migrate":
                 payload = _migrate(plan, dry_run=args.dry_run)

package/enhancements/MANIFEST.json

@@ -1,7 +1,7 @@
 {
-  "syncedAt": "2026-09-05T18:24:52.904Z",
+  "syncedAt": "2026-09-07T07:30:55.059Z",
   "syncedFrom": "vendor/skill-garden",
-  "sourceCommit": "6199ab8b2e0259ff695d70797943ea1ae97e099c",
+  "sourceCommit": "3e08ded44107ae8d3e1c04e5f1cdb3014655f038",
   "common": {
     "codexSkills": [
       "aliyun-ops",

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "flower-trellis",
-  "version": "0.6.5",
+  "version": "0.6.7",
   "description": "一键安装/升级 Trellis 并自动融合 skill-garden 强化包(默认 Claude + agents)",
   "type": "module",
   "bin": {
@@ -70,9 +70,9 @@
     "commit-and-tag-version": "^12.7.3"
   },
   "flowerReleaseNotes": {
-    "version": "0.6.5",
+    "version": "0.6.7",
     "source": "CHANGELOG.md",
-    "body": "### ✨ 新功能 Features\n\n* **cli:** 优化调用契约与帮助体验 ([b7a39db](https://github.com/SilentFlower/flower-trellis/commit/b7a39dbda2042643c3e15dd47caebe7c83242548))\n* **codex:** 为 Astra 添加 SessionStart 工作流提示 ([1d79835](https://github.com/SilentFlower/flower-trellis/commit/1d79835f4bea1782f5774ff8c14a6263742b1677))\n* **telemetry:** 采集平台活跃与核心操作质量 ([08598bf](https://github.com/SilentFlower/flower-trellis/commit/08598bf26638567b9183150d7c258e2f801046a4))\n\n\n### 🐛 修复 Bug Fixes\n\n* **hooks:** 分段注入启动上下文并保留额度 ([5eaf6af](https://github.com/SilentFlower/flower-trellis/commit/5eaf6afd7c7b088e8421f3b176d0d79ccb9cdba2))\n* **plugin:** 兼容旧 RD Guide 离线升级 ([fcec390](https://github.com/SilentFlower/flower-trellis/commit/fcec3905629dd31bc3f113ac28bf64139311324e))",
+    "body": "### ✨ 新功能 Features\n\n* **bootstrap:** 完善团队版本记录与 CLI 安装引导 ([e86217c](https://github.com/SilentFlower/flower-trellis/commit/e86217c5a121b35509ad972540c2c0adf3763b64))\n\n\n### 🐛 修复 Bug Fixes\n\n* **worktree:** 补齐 Flower 安装记录继承与版本诊断 ([17ad63e](https://github.com/SilentFlower/flower-trellis/commit/17ad63efd9f56ecf491c9402ef92469c70db3ea1))\n\n\n### ♻️ 重构 Refactor\n\n* **check-all:** 同步检查优化与回归验证 ([1409d42](https://github.com/SilentFlower/flower-trellis/commit/1409d421884cfe35a95342b6e68b3b7b80496e29))\n\n\n### 🧰 维护 Maintenance\n\n* **trellis:** 同步 Flower 0.6.6 工作流与 hooks ([11ae2b9](https://github.com/SilentFlower/flower-trellis/commit/11ae2b96b543da1a01e8a1871471d0752f1a04af))\n* **trellis:** 同步本地安装产物与 Flower 记录 ([5a78ca0](https://github.com/SilentFlower/flower-trellis/commit/5a78ca01434e26287caaed8b3e68321a1efd7cc7))",
     "truncated": false
   },
   "optionalDependencies": {

package/src/assets/flower_session_start.py

@@ -27,7 +27,7 @@ When executing the current task:
 - Treat required steps, required references, phase boundaries, and output templates in applicable SKILL and WORKFLOW instructions as execution and delivery checks.
 - Before a step, review its rules and required references. Reuse material already read in full and unchanged; search matches are not full reads.
 - Preserve required heading levels, section order, and conditional sections in specified templates. General brevity or no-heading preferences apply to ordinary prose and do not justify flattening, shortening, or reshaping a specified template.
-- Resolve conflicts by instruction hierarchy and respect the user's current explicit authorization. Do not invent additional confirmation steps or claim that this hint or a SKILL overrides all host rules.
+- Resolve conflicts by instruction hierarchy. Follow the owning workflow's phase-transition and review requirements, checking the scope of prior authorization; do not infer approval of the final plan from permission to begin planning.
 - Before claiming "read", "checked", or "complete", verify actual tool records and artifacts. Successful reading and compliant execution are separate facts.
 - When corrected, review the applicable rules, execution records, and actual result before repairing it. If evidence is missing, state uncertainty. Do not invent causes such as "not read", "forgot", or "file missing", or consult unrelated rules in place of the relevant ones.
 </trellis-astra-workflow-hint>"""

package/src/assets/flower_update_hook.py

@@ -1,16 +1,17 @@
 #!/usr/bin/env python3
 # -*- coding: utf-8 -*-
-"""SessionStart 启动更新检查 hook。
+"""复用 SessionStart 升级入口，检测 CLI 缺失并提供对话安装引导。
 
-脚本只做只读检查和上下文注入:调用 `flower-trellis self-check --json`,
-发现可执行更新时输出 `<flower-update>` 块。失败、离线、无更新或关闭检查时静默退出,
-避免影响 Codex / Claude Code 正常启动。
+只读检测，不执行 npm；CLI 已安装时沿用 self-check 更新检查。
 """
 
 from __future__ import annotations
 
+import argparse
 import json
 import os
+import re
+import shutil
 import subprocess
 import sys
 from pathlib import Path
@@ -18,6 +19,105 @@ from pathlib import Path
 
 ACTIONABLE_STATUSES = {"update_available", "project_out_of_sync"}
 SELF_CHECK_TIMEOUT_SECONDS = 30
+BOOTSTRAP_STATUSES = {"cli_missing", "cli_unavailable", "project_version_unavailable", "prerequisites_missing"}
+MAX_LOCK_BYTES = 2 * 1024 * 1024
+
+
+def _executable_status(name: str) -> str:
+    """检查 PATH，区分缺失与已有但不可执行的入口。"""
+    if shutil.which(name):
+        return "available"
+    names = [name]
+    if os.name == "nt":
+        names.extend(name + suffix for suffix in os.environ.get("PATHEXT", ".COM;.EXE;.BAT;.CMD").split(";"))
+    for directory in os.get_exec_path():
+        if any(os.path.lexists(os.path.join(directory, candidate)) for candidate in names):
+            return "unavailable"
+    return "missing"
+
+
+def _locked_flower_version(project_dir: Path) -> str:
+    """只读取受支持的内置锁条目，拒绝把未知版本拼入安装命令。"""
+    lock_path = project_dir / ".flower" / "plugin-lock.json"
+    if lock_path.parent.is_symlink() or lock_path.is_symlink() or not lock_path.is_file():
+        raise ValueError("项目缺少普通文件形式的 .flower/plugin-lock.json")
+    if lock_path.stat().st_size > MAX_LOCK_BYTES:
+        raise ValueError("项目锁超过读取上限")
+    lock = json.loads(lock_path.read_text(encoding="utf-8"))
+    if not isinstance(lock, dict) or type(lock.get("schemaVersion")) is not int or lock["schemaVersion"] != 1:
+        raise ValueError("项目锁 schema 不受支持")
+    plugins, roots = lock.get("plugins"), lock.get("roots")
+    if not isinstance(plugins, list) or not isinstance(roots, list) or any(not isinstance(root, str) for root in roots):
+        raise ValueError("项目锁 plugins/roots 结构无效")
+    if any(not isinstance(plugin, dict) for plugin in plugins):
+        raise ValueError("项目锁 Plugin 条目无效")
+    matches = [plugin for plugin in plugins if plugin.get("id") == "flower/skill-garden"]
+    if len(matches) != 1:
+        raise ValueError("项目锁缺少唯一的 flower/skill-garden 条目")
+    plugin = matches[0]
+    source = plugin.get("source")
+    if (
+        not isinstance(source, dict)
+        or source.get("id") != "flower"
+        or source.get("type") != "builtin"
+        or not isinstance(source.get("reference"), str)
+        or source.get("reference") not in {
+            "package:skill-garden:old", "package:skill-garden:0.5", "package:skill-garden:0.6",
+        }
+    ):
+        raise ValueError("项目锁的 Skill-Garden 来源不是受支持的内置来源")
+    version = plugin.get("version")
+    match = re.fullmatch(r"(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)\.(0|[1-9][0-9]*)(?:-([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?(?:\+([0-9A-Za-z-]+(?:\.[0-9A-Za-z-]+)*))?", version) if isinstance(version, str) and len(version) <= 256 else None
+    if not match or any(int(part) > 9007199254740991 for part in match.groups()[:3]):
+        raise ValueError("项目 Flower 版本不是完整有效的 SemVer")
+    if match[4] and any(part.isdigit() and len(part) > 1 and part.startswith("0") for part in match[4].split(".")):
+        raise ValueError("项目 Flower 预发布版本包含非法数字标识")
+    return version
+
+
+def _check_cli(project_dir: Path) -> dict | None:
+    """只读检查本机入口，返回安装或环境诊断；可用时返回空值。"""
+    if not project_dir.is_dir():
+        return {"status": "cli_unavailable", "reason": "目标项目目录不存在"}
+    cli_status = _executable_status("flower-trellis")
+    if cli_status == "available":
+        return None
+    if cli_status == "unavailable":
+        return {"status": "cli_unavailable", "reason": "PATH 中已有 Flower 入口但不可执行，请检查权限、链接与解释器"}
+    try:
+        version = _locked_flower_version(project_dir)
+    except (OSError, ValueError) as exc:
+        return {"status": "project_version_unavailable", "reason": f"Flower CLI 缺失，项目版本无法确认：{exc}"}
+    missing = [name for name in ("node", "npm") if _executable_status(name) != "available"]
+    if missing:
+        return {"status": "prerequisites_missing", "version": version, "reason": f"Flower CLI 缺失，请先准备可执行的 {', '.join(missing)}"}
+    return {"status": "cli_missing", "version": version, "command": f"npm install -g flower-trellis@{version}"}
+
+
+def _format_bootstrap(data: dict) -> str:
+    """生成唯一的对话安装协议，检测脚本自身不执行安装。"""
+    lines = [
+        "<flower-cli-bootstrap>",
+        "priority: blocking_confirmation_required",
+        f"status: {data['status']}",
+    ]
+    if data.get("version"):
+        lines.append(f"project_flower: {data['version']}")
+    if data.get("reason"):
+        lines.append("reason: " + json.dumps(data["reason"], ensure_ascii=False))
+    if data.get("command"):
+        lines.extend([
+            f"recommended_command: {data['command']}",
+            "ai_instruction: 告知成员本机缺少 Flower CLI，展示锁定版本和 recommended_command；说明全局 npm 安装会同步本机 Trellis 命令。先征得当前成员确认，确认前禁止执行 recommended_command；当前对话已明确授权这次安装时不重复确认。",
+            "verification: 安装返回成功后，在目标项目执行 flower-trellis -v 核对 CLI 首行版本，再执行 flower-trellis self-check --json --target <目标项目>；参数按所在 shell 引用。确认 CLI 可用后继续原请求，不把项目锁视为内容完整性证明，不隐式执行 init/update/self-update。",
+        ])
+    else:
+        lines.append("ai_instruction: 说明诊断原因与缺失前提；版本未知时请维护者补齐有效项目锁，不依据旧 manifest 或猜测 latest 安装；入口异常先修复 PATH、权限或解释器。")
+    lines.extend([
+        "failure_policy: 成员拒绝后本次对话不重复追问；安装或验证失败如实报告，不自动提权、不循环安装。依赖 CLI 的操作说明尚未满足的前提；本次已处理的相同引导不重复执行。",
+        "</flower-cli-bootstrap>",
+    ])
+    return "\n".join(lines)
 
 
 def _debug(message: str) -> None:
@@ -45,6 +145,9 @@ def _project_dir(hook_input: dict) -> Path:
 
 def _run_self_check(project_dir: Path) -> dict | None:
     """执行 flower-trellis self-check 并解析 JSON。"""
+    bootstrap = _check_cli(project_dir)
+    if bootstrap:
+        return bootstrap
     try:
         result = subprocess.run(
             [
@@ -61,18 +164,19 @@ def _run_self_check(project_dir: Path) -> dict | None:
             timeout=SELF_CHECK_TIMEOUT_SECONDS,
             cwd=str(project_dir),
         )
-    except (subprocess.TimeoutExpired, FileNotFoundError, PermissionError) as exc:
-        _debug(str(exc))
-        return None
+    except subprocess.TimeoutExpired:
+        return {"status": "cli_unavailable", "reason": "Flower CLI 检查超时，不能据此判定未安装"}
+    except OSError as exc:
+        return {"status": "cli_unavailable", "reason": f"Flower 入口存在但执行失败，请检查 PATH、权限与解释器：{exc}"}
     if result.returncode != 0:
-        _debug(result.stderr.strip() or f"退出码 {result.returncode}")
-        return None
+        _debug(result.stderr.strip())
+        return {"status": "cli_unavailable", "reason": f"Flower CLI 检查退出码 {result.returncode}，请先诊断现有安装"}
     try:
         data = json.loads(result.stdout)
     except json.JSONDecodeError as exc:
         _debug(f"JSON 解析失败:{exc}")
-        return None
-    return data if isinstance(data, dict) else None
+        return {"status": "cli_unavailable", "reason": "Flower CLI 返回的检查结果不是有效 JSON"}
+    return data if isinstance(data, dict) and isinstance(data.get("status"), str) else {"status": "cli_unavailable", "reason": "Flower CLI 检查结果结构无效"}
 
 
 def _json_bool(value: object) -> str:
@@ -219,15 +323,32 @@ def _emit_context(context: str, system_message: str) -> None:
     print(json.dumps(result, ensure_ascii=False), flush=True)
 
 
-def main() -> None:
+def main(argv: list[str] | None = None) -> None:
+    """处理宿主启动或手动只读检测入口并输出上下文。
+
+    Args:
+        argv: 显式参数列表，省略时读取进程参数。
+    Returns:
+        无返回值；通过标准输出返回宿主 JSON。
+    """
+    parser = argparse.ArgumentParser(description="Flower CLI 安装与升级只读检测")
+    parser.add_argument("--bootstrap-only", action="store_true")
+    parser.add_argument("--target", type=Path)
+    args = parser.parse_args(argv)
+    if not args.bootstrap_only and (os.environ.get("TRELLIS_HOOKS") == "0" or os.environ.get("TRELLIS_DISABLE_HOOKS") == "1" or os.environ.get("CODEX_NON_INTERACTIVE") == "1"):
+        return
     try:
-        hook_input = json.loads(sys.stdin.read() or "{}")
+        hook_input = {} if args.bootstrap_only else json.loads(sys.stdin.read() or "{}")
         if not isinstance(hook_input, dict):
             hook_input = {}
     except json.JSONDecodeError:
         hook_input = {}
 
-    data = _run_self_check(_project_dir(hook_input))
+    project_dir = args.target.resolve() if args.target else _project_dir(hook_input)
+    data = _check_cli(project_dir) if args.bootstrap_only else _run_self_check(project_dir)
+    if data and data.get("status") in BOOTSTRAP_STATUSES:
+        _emit_context(_format_bootstrap(data), "Flower CLI 需要安装确认或环境诊断")
+        return
     if not data or data.get("status") not in ACTIONABLE_STATUSES:
         return
     _emit_context(_format_context(data), _system_message(data))

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

@@ -6,6 +6,7 @@ import {
   ENHANCEMENT_SKILL_TARGETS,
 } from "../../constants.js";
 import { readLegacyManifestStatus } from "../../lib/manifest.js";
+import { projectFlowerMetadata } from "./project-metadata.js";
 import { shouldInstallName } from "../../lib/skill-filter.js";
 import { listCanonicalTreeFiles, isVolatileTreeArtifact } from "../../plugin/integrity/canonical-tree.js";
 import {
@@ -893,6 +894,9 @@ export function projectSkillGardenContent(options) {
       }
     }
   }
+  const metadata = projectFlowerMetadata(projectRoot, resolved.id);
+  mutations.push(...metadata.mutations);
+  for (const [key, value] of metadata.payloads) payloads.set(key, value);
   return {
     mutations: mutations.sort((left, right) => compareUtf8(left.target, right.target)),
     payloads,

package/src/builtin-plugins/skill-garden/project-metadata.js

@@ -0,0 +1,41 @@
+import fs from "node:fs";
+import path from "node:path";
+import { planLegacyManifestMigration } from "../../lib/manifest.js";
+import { contentMutationKey } from "../../plugin/install/content-projector.js";
+import { hashContent, hashFileIfExists } from "../../plugin/install/content-hash.js";
+import { mergeFlowerIgnoreRules } from "../../plugin/state/ignore-rules.js";
+
+/**
+ * 规划 Flower 共享记录与旧配置迁移，不声明用户配置的独占 ownership。
+ *
+ * @param {string} projectRoot 目标项目根
+ * @param {string} owner 内置 Plugin ID
+ * @returns {{mutations:object[],payloads:Map<string,Buffer>}} 事务目标及写入内容
+ */
+export function projectFlowerMetadata(projectRoot, owner) {
+  const writes = planLegacyManifestMigration(projectRoot);
+  const localIgnore = path.join(projectRoot, ".flower/.gitignore");
+  const localText = hashFileIfExists(localIgnore) === null ? "" : fs.readFileSync(localIgnore, "utf8");
+  writes.push({ path: ".flower/.gitignore", content: Buffer.from(mergeFlowerIgnoreRules(localText)) });
+  const rootIgnore = path.join(projectRoot, ".gitignore");
+  if (hashFileIfExists(rootIgnore) !== null) {
+    writes.push({ path: ".gitignore", content: Buffer.from(mergeFlowerIgnoreRules(fs.readFileSync(rootIgnore, "utf8"), { root: true })) });
+  }
+  const mutations = [];
+  const payloads = new Map();
+  for (const entry of writes) {
+    const mutation = {
+      owner,
+      target: entry.path,
+      operation: entry.content === null ? "remove" : "write",
+      beforeHash: hashFileIfExists(path.join(projectRoot, ...entry.path.split("/"))),
+      afterHash: entry.content === null ? null : hashContent(entry.content),
+      source: "flower:project-metadata",
+      allowUnownedWrite: true,
+      allowUnownedRemove: true,
+    };
+    mutations.push(mutation);
+    if (entry.content !== null) payloads.set(contentMutationKey(mutation), entry.content);
+  }
+  return { mutations, payloads };
+}

package/src/commands/self-check.js

@@ -14,7 +14,9 @@ function printSelfCheckHelp() {
   --force-remote   强制检查远端版本
   --target <dir>   要检查的项目目录
 
-该命令供 SessionStart hook 和自动化读取，成功时始终输出 JSON。`);
+该命令供 SessionStart hook 和自动化读取，成功时始终输出 JSON。
+project.flowerVersionStatus 区分 known/unknown；记录缺失且无已知更新时返回
+project_unknown，不能以 CLI 最新推断项目也已更新。`);
 }
 
 /**

package/src/commands/self-update.js

@@ -199,7 +199,9 @@ async function executeSelfUpdate(ctx) {
   }
 
   if (!shouldInstallFlower && !projectOnly && check.status !== "project_out_of_sync") {
-    console.log(`  · 当前状态:${check.status},无需执行 self-update`);
+    console.log(check.status === "project_unknown"
+      ? "  · 项目 Flower 版本无法确认，未执行更新；worktree 可先通过 prepare --inherit-flower 补齐安装记录"
+      : `  · 当前状态:${check.status},无需执行 self-update`);
     return;
   }
 

package/src/commands/update-check.js

@@ -106,11 +106,11 @@ export async function updateCheck(ctx) {
     const cachePath = updateCheckCachePath(ctx.target);
     console.log(`settings: ${settingsPath(ctx.target)}`);
     console.log(`cache: ${cachePath}`);
-    console.log(`legacy manifest: ${manifestPath(ctx.target)}`);
+    if (manifest) console.log(`legacy manifest (待迁移): ${manifestPath(ctx.target)}`);
     console.log(JSON.stringify(readUpdateCheck(ctx.target), null, 2));
-    if (!manifest) console.log("  · manifest 不存在,当前显示默认策略");
+    if (!manifest && !fs.existsSync(settingsPath(ctx.target))) console.log("  · settings 不存在,当前显示默认策略");
     if (!fs.existsSync(cachePath)) {
-      console.log("  · cache 不存在,当前显示默认或旧 manifest 兼容缓存");
+      console.log("  · cache 不存在,当前显示默认或旧记录兼容缓存");
     }
     return;
   }