guarantee-based-coding 0.2.0__py3-none-any.whl → 0.2.2__py3-none-any.whl

gbc/__init__.py

@@ -18,4 +18,4 @@
 显式、可执行、可验证的保证。本包是该方法的实现，也是它的第一个使用者。
 """
 
-__version__ = "0.2.0"
+__version__ = "0.2.2"

gbc/app/config/project.py

@@ -12,24 +12,37 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
+import os
 from pathlib import Path
 
 
-# 初始化当前路径：进程启动时的 cwd。CLI 单次命令默认就用这个——“当前项目 = 跑命令时所在目录”，
-# 无需环境变量，不会静默回退到包安装位置。常驻服务（mcp up / editor up）cwd 不可靠，
-# 它们自己收显式参数覆盖，不依赖这个默认值。
+GBC_PROJECT_ROOT = "GBC_PROJECT_ROOT"
+
+
+def _normalize_project_path(path: str | os.PathLike[str]) -> Path:
+    """Return an absolute, normalized project path without requiring it to exist."""
+    raw_path = os.fspath(path)
+    if not raw_path.strip():
+        raise ValueError("project path must not be blank")
+    return Path(raw_path).expanduser().resolve(strict=False)
+
+
+# 初始化当前路径：进程启动时固定按 GBC_PROJECT_ROOT > cwd 选择一次，不向上搜索。
 def _init_current_project() -> Path:
-    return Path.cwd()
+    configured_root = os.environ.get(GBC_PROJECT_ROOT)
+    if configured_root is not None and configured_root.strip():
+        return _normalize_project_path(configured_root)
+    return _normalize_project_path(Path.cwd())
+
 
-# 会被使用的当前路径变量
 CURRENT_PROJECT = _init_current_project()
 
-# 更新当前路径
-def set_current_project(new_path: str):
-    new_path = Path(new_path)
 
+def set_current_project(new_path: str | os.PathLike[str]) -> None:
+    """Explicitly override the current project root."""
     global CURRENT_PROJECT
-    CURRENT_PROJECT = new_path
+    CURRENT_PROJECT = _normalize_project_path(new_path)
+
 
-def get_current_project():
-    return CURRENT_PROJECT
+def get_current_project() -> Path:
+    return CURRENT_PROJECT

gbc/app/i18n/lang.py

@@ -12,18 +12,24 @@
 # See the License for the specific language governing permissions and
 # limitations under the License.
 
-"""语言判定 + **从文件自动发现受支持语言**。
+"""语言判定、用户级持久偏好与从文件自动发现受支持语言。
 
 关键设计:受支持语言不硬编码,而是扫描资源文件推导——放一个 `catalog/ja.json`
 (以及可选的 `texts/*.ja.md`)就自动支持日语,无需改代码。
 
-判定优先级(高→低):显式 lang 参数 > 环境变量 GBC_LANG > 系统 locale > 默认 en。
+判定优先级(高→低):显式 lang 参数 > 环境变量 GBC_LANG > 持久偏好 >
+系统 locale > 默认 en。
 """
 import locale
 import os
+from pathlib import Path
+import tempfile
+
 from gbc.app.assets import I18N_CATALOG_DIR as _CATALOG_DIR
 
 DEFAULT_LANG = "en"
+GBC_CONFIG_HOME = "GBC_CONFIG_HOME"
+LANG_PREFERENCE_FILENAME = "lang"
 
 # 进程内当前语言(命令入口解析一次后 set_lang 固定;库函数读 current_lang)。
 _current: str = DEFAULT_LANG
@@ -53,16 +59,88 @@ def normalize(raw: str | None) -> str | None:
     return None
 
 
+def _preference_dir() -> Path:
+    """返回用户语言偏好目录,不查询项目目录。"""
+    configured = os.environ.get(GBC_CONFIG_HOME)
+    if configured:
+        return Path(configured)
+
+    if os.name == "nt":
+        appdata = os.environ.get("APPDATA")
+        if appdata:
+            return Path(appdata) / "gbc"
+
+    xdg_config_home = os.environ.get("XDG_CONFIG_HOME")
+    if xdg_config_home:
+        return Path(xdg_config_home) / "gbc"
+    return Path.home() / ".config" / "gbc"
+
+
+def _preference_file() -> Path:
+    return _preference_dir() / LANG_PREFERENCE_FILENAME
+
+
+def read_language_preference() -> str | None:
+    """读取格式严格的用户语言偏好;缺失、损坏或不可读时返回 None。"""
+    try:
+        content = _preference_file().read_bytes().decode("utf-8")
+    except (OSError, UnicodeError):
+        return None
+
+    for lang in supported_langs():
+        if content == f"{lang}\n":
+            return lang
+    return None
+
+
+def set_language_preference(value: str) -> str | None:
+    """原子替换用户语言偏好;``auto`` 幂等删除偏好文件。"""
+    preference_file = _preference_file()
+    if value == "auto":
+        preference_file.unlink(missing_ok=True)
+        return None
+
+    if not isinstance(value, str) or normalize(value) != value:
+        raise ValueError(f"unsupported language: {value!r}")
+
+    preference_file.parent.mkdir(parents=True, exist_ok=True)
+    temporary_file: Path | None = None
+    try:
+        with tempfile.NamedTemporaryFile(
+            mode="w",
+            encoding="utf-8",
+            dir=preference_file.parent,
+            prefix=f".{LANG_PREFERENCE_FILENAME}.",
+            delete=False,
+            newline="\n",
+        ) as handle:
+            temporary_file = Path(handle.name)
+            handle.write(f"{value}\n")
+        os.replace(temporary_file, preference_file)
+    finally:
+        if temporary_file is not None:
+            try:
+                temporary_file.unlink(missing_ok=True)
+            except OSError:
+                pass
+    return value
+
+
 def resolve_lang(explicit: str | None = None) -> str:
     """按优先级判定语言,永远返回一个受支持码(兜底 DEFAULT_LANG)。
 
-    显式 explicit > 环境变量 GBC_LANG > 系统 locale > DEFAULT_LANG。
+    显式 explicit > 环境变量 GBC_LANG > 持久偏好 > 系统 locale >
+    DEFAULT_LANG。无效的高优先级值会继续向后判定。
     """
     for candidate in (explicit, os.environ.get("GBC_LANG")):
         norm = normalize(candidate)
         if norm:
             return norm
 
+    norm = normalize(read_language_preference())
+    if norm:
+        return norm
+
     try:
         sys_lang, _ = locale.getlocale()
     except (ValueError, TypeError):

gbc/app/intent/base.py

@@ -24,9 +24,14 @@
 gbc.md 解析单源复用 gbc.app.utils.gbc_md。
 """
 from pathlib import Path
+import re
+import threading
 
 from gbc.app.utils import gbc_md as gf
-from gbc.app.models.errors import IntentDocError
+from gbc.app.models.errors import IntentDocError, IntentConflictError
+from gbc.app.models.meta import FileMeta
+from gbc.app.utils.json_model_operator import load_model_from_json
+from gbc.app.utils.safe_file_writer import SafeFileWriter
 
 GBC_FILE = "gbc.md"
 
@@ -160,6 +165,44 @@ def show(gbc_root: Path, rel: str) -> str:
     return "\n".join(lines)
 
 
+# ---- 文件条目 → .gbc json 只读视图 -------------------------------------------
+
+def file_meta_view(gbc_root: Path, path: str) -> dict | None:
+    """返回一个文件条目对应的 .gbc json(FileMeta)只读可读视图;json 缺失/损坏返回 None。
+
+    path 是完整语义文件路径(如 "app/main.py";根层文件即 "main.py")。在 base 内做完整校验:
+    复用 _validate_path(拒绝对路径/.. /空段/首尾空白/反斜杠),且 root("")、folder 尾斜杠、
+    空 name 均非法——只接受指向 file 的路径。非法抛 IntentDocError,由上层表面转 400。
+
+    定位规则与 file_utils.to_gbc_json_path 一致:源码 ``<rel>/<name>`` 的元数据落在
+    .gbc 镜像下 ``<gbc_root>/<rel>/gbc.<name>.json``(gbc_root 即 .gbc 镜像层,对应项目根)。
+    只读视图——绝不写盘、绝不创建缺失的 json、解析失败静默返回 None。
+    """
+    _validate_path(path)
+    if path == "" or path.endswith("/"):
+        raise IntentDocError("exc.doc_flat_bad_path", path=path)
+    rel, _, name = path.rpartition("/")
+    json_path = (gbc_root / rel / f"gbc.{name}.json") if rel else (gbc_root / f"gbc.{name}.json")
+    if not json_path.is_file():
+        return None
+    try:
+        meta = load_model_from_json(json_path, FileMeta)
+    except (OSError, ValueError):  # 缺失/损坏/不符合模型 → 只读视图不抛错
+        return None
+    return {
+        "provides": [
+            {"id": gid, "desc": g.desc, "disabled": g.disabled,
+             "dependents": list(g.dependents)}
+            for gid, g in meta.provides.items()
+        ],
+        "depends_on": [
+            {"symbol": d.symbol, "provider": d.symbol.split(":", 1)[0],
+             "guarantees": list(d.guarantees)}
+            for d in meta.depends_on
+        ],
+    }
+
+
 # ---- 整树读写(供 web 编辑器) -----------------------------------------------
 
 def empty_tree(gbc_root: Path) -> dict:
@@ -306,3 +349,373 @@ def migrate(gbc_root: Path) -> list[str]:
             md.write_text(new, encoding="utf-8")
             changed.append(str(md))
     return changed
+
+
+# ---- flat 语义模型(供 web 编辑器) -------------------------------------------
+
+# root path 为 "";folder path 以 "/" 结尾;file path 不以 "/" 结尾。
+# folder node = {kind:"folder", intent, constraints};file node = {kind:"file", desc}。
+
+
+def _last_segment(path: str) -> str:
+    """"app/" -> "app";"app/main.py" -> "main.py";"" -> ""。"""
+    body = path[:-1] if path.endswith("/") else path
+    return body.rsplit("/", 1)[-1]
+
+
+def _parent_flat_key(path: str) -> str:
+    """flat 路径的父文件夹 key(""/"a/" 都回 "")。"""
+    body = path[:-1] if path.endswith("/") else path
+    idx = body.rfind("/")
+    return body[:idx] + "/" if idx != -1 else ""
+
+
+def _children_paths(flat: dict, folder_key: str) -> list[str]:
+    return [p for p in flat if p != folder_key and _parent_flat_key(p) == folder_key]
+
+
+def _node_eq(a, b) -> bool:
+    """语义节点相等:kind 参与比较(区分类型),folder 比 intent+constraints,file 比 desc。"""
+    if a is None or b is None:
+        return a is b
+    if not isinstance(a, dict) or not isinstance(b, dict):
+        return False
+    if a.get("kind") != b.get("kind"):
+        return False
+    kind = a.get("kind")
+    if kind == "folder":
+        return a.get("intent", "") == b.get("intent", "") and a.get("constraints", "") == b.get("constraints", "")
+    if kind == "file":
+        return a.get("desc", "") == b.get("desc", "")
+    return False
+
+
+def nested_to_flat(node: dict) -> dict:
+    """纯函数:nested dict 树(如 read_tree 输出) -> flat {path: node}。"""
+    flat: dict[str, dict] = {}
+
+    def walk(n: dict, folder_key: str) -> None:
+        flat[folder_key] = {"kind": "folder",
+                            "intent": n.get("intent", ""),
+                            "constraints": n.get("constraints", "")}
+        for e in n.get("entries", []):
+            name = e["name"].rstrip("/")
+            if _is_dir_name(e["name"]):
+                child_key = (f"{folder_key}{name}" if folder_key else name) + "/"
+                walk(e.get("child") or {}, child_key)
+            else:
+                file_key = f"{folder_key}{name}" if folder_key else name
+                flat[file_key] = {"kind": "file", "desc": e.get("desc", "")}
+
+    walk(node, "")
+    return flat
+
+
+def flat_to_nested(flat: dict, name: str = "") -> dict:
+    """纯函数:flat {path: node} -> nested dict 树(根)。name 为根节点展示名。"""
+
+    def build(folder_key: str) -> dict:
+        node = flat.get(folder_key, {"kind": "folder", "intent": "", "constraints": ""})
+        nested = {
+            "name": _last_segment(folder_key),
+            "path": folder_key.rstrip("/"),
+            "intent": node.get("intent", ""),
+            "constraints": node.get("constraints", ""),
+            "entries": [],
+        }
+        for path in sorted(_children_paths(flat, folder_key)):
+            child = flat[path]
+            seg = _last_segment(path)
+            if child.get("kind") == "folder":
+                nested["entries"].append({"name": f"{seg}/", "child": build(path)})
+            else:
+                nested["entries"].append({"name": seg, "desc": child.get("desc", "")})
+        return nested
+
+    root = build("")
+    root["name"] = name
+    return root
+
+
+def _validate_path(path: str) -> None:
+    """拒绝绝对路径、..、空段、首尾空白、反斜杠;root "" 合法。"""
+    if not isinstance(path, str):
+        raise IntentDocError("exc.doc_flat_bad_path", path=repr(path))
+    if path == "":
+        return
+    if path != path.strip():
+        raise IntentDocError("exc.doc_flat_bad_path", path=path)
+    if "\\" in path:
+        raise IntentDocError("exc.doc_flat_bad_path", path=path)
+    body = path[:-1] if path.endswith("/") else path
+    if body.startswith("/") or re.match(r"^[A-Za-z]:", body):
+        raise IntentDocError("exc.doc_flat_bad_path", path=path)
+    segs = body.split("/")
+    if "" in segs or any(s in (".", "..") for s in segs):
+        raise IntentDocError("exc.doc_flat_bad_path", path=path)
+
+
+def _validate_node(path: str, node) -> None:
+    if not isinstance(node, dict):
+        raise IntentDocError("exc.doc_flat_bad_node", path=path, reason="not an object")
+    kind = node.get("kind")
+    expected = "folder" if (path == "" or path.endswith("/")) else "file"
+    if kind != expected:
+        raise IntentDocError("exc.doc_flat_bad_node", path=path,
+                             reason=f"kind must be '{expected}'")
+    if kind == "folder":
+        for key in ("intent", "constraints"):
+            if key in node and not isinstance(node[key], str):
+                raise IntentDocError("exc.doc_flat_bad_node", path=path, reason=f"{key} must be a string")
+    else:
+        if "desc" in node and not isinstance(node["desc"], str):
+            raise IntentDocError("exc.doc_flat_bad_node", path=path, reason="desc must be a string")
+
+
+def _validate_flat(flat: dict) -> None:
+    if not isinstance(flat, dict):
+        raise IntentDocError("exc.doc_flat_bad_node", path="<root>", reason="flat must be an object")
+    if "" not in flat:
+        raise IntentDocError("exc.doc_flat_bad_node", path="", reason="root node is required")
+    for path, node in flat.items():
+        _validate_path(path)
+        _validate_node(path, node)
+    for path in flat:
+        if path == "":
+            continue
+        parent = _parent_flat_key(path)
+        if parent not in flat or flat[parent].get("kind") != "folder":
+            raise IntentDocError("exc.doc_flat_missing_ancestor", path=path, parent=parent)
+
+
+def read_flat(gbc_root: Path) -> dict:
+    """读磁盘 -> flat map。gbc_root 不存在时回仅根节点的空树。"""
+    if not gbc_root.exists():
+        return {"": {"kind": "folder", "intent": "", "constraints": ""}}
+    return nested_to_flat(read_tree(gbc_root))
+
+
+# ---- 选择性保存(冲突感知,最小写盘) -------------------------------------------
+
+_save_locks: dict[str, threading.Lock] = {}
+_save_locks_guard = threading.Lock()
+
+
+def _lock_for(root_key: str) -> threading.Lock:
+    with _save_locks_guard:
+        if root_key not in _save_locks:
+            _save_locks[root_key] = threading.Lock()
+        return _save_locks[root_key]
+
+
+def _entries_for_folder(flat: dict, folder_key: str) -> list[gf.Entry]:
+    entries: list[gf.Entry] = []
+    for path in sorted(_children_paths(flat, folder_key)):
+        node = flat[path]
+        seg = _last_segment(path)
+        if node.get("kind") == "folder":
+            entries.append(gf.Entry(name=f"{seg}/", is_dir=True, desc=node.get("intent", "")))
+        else:
+            entries.append(gf.Entry(name=seg, is_dir=False, desc=node.get("desc", "")))
+    return entries
+
+
+def _reconcile_entries(disk_entries: list[gf.Entry], target_entries: list[gf.Entry]) -> list[gf.Entry]:
+    """保留盘上条目顺序(未涉及条目原样),更新已存在条目的 desc,新条目追加到末尾。"""
+    target_map = {(e.name.rstrip("/"), e.is_dir): e for e in target_entries}
+    result: list[gf.Entry] = []
+    seen: set[tuple[str, bool]] = set()
+    for e in disk_entries:
+        key = (e.name.rstrip("/"), e.is_dir)
+        te = target_map.get(key)
+        if te is not None:
+            result.append(gf.Entry(name=e.name, is_dir=e.is_dir, desc=te.desc))
+            seen.add(key)
+    for te in target_entries:
+        key = (te.name.rstrip("/"), te.is_dir)
+        if key not in seen:
+            result.append(te)
+    return result
+
+
+def _docs_equal(a: gf.ParsedDoc, b: gf.ParsedDoc) -> bool:
+    if a.intent != b.intent or a.constraints != b.constraints:
+        return False
+    if len(a.entries) != len(b.entries):
+        return False
+    for ea, eb in zip(a.entries, b.entries):
+        if ea.name != eb.name or ea.is_dir != eb.is_dir or ea.desc != eb.desc:
+            return False
+    return True
+
+
+def _render_doc(flat: dict, folder_key: str, order_source: gf.ParsedDoc | None) -> gf.ParsedDoc:
+    node = flat.get(folder_key, {"kind": "folder", "intent": "", "constraints": ""})
+    entries = _entries_for_folder(flat, folder_key)
+    if order_source is not None:
+        entries = _reconcile_entries(order_source.entries, entries)
+    return gf.ParsedDoc(intent=node.get("intent", ""), constraints=node.get("constraints", ""),
+                        entries=entries)
+
+
+def _write_doc_atomic(gbc_root: Path, rel: str, text: str) -> Path:
+    p = _doc_path(gbc_root, rel)
+    p.parent.mkdir(parents=True, exist_ok=True)
+    with SafeFileWriter(p).open(mode="w", encoding="utf-8") as f:
+        f.write(text)
+    return p
+
+
+def _apply_flat(gbc_root: Path, disk_flat: dict, merged_flat: dict) -> tuple[list[str], list[str]]:
+    """把 merged 落到磁盘:只重写内容变化的 gbc.md;删除文件夹时 unlink 子树 gbc.md,绝不碰 json。"""
+    written: list[str] = []
+    deleted: list[str] = []
+
+    merged_folders = {p for p in merged_flat if p == "" or p.endswith("/")}
+    disk_folders = {p for p in disk_flat if p == "" or p.endswith("/")}
+
+    # 先删(深路径在前),避免残留孤儿 gbc.md
+    for f in sorted(disk_folders - merged_folders, key=len, reverse=True):
+        p = _doc_path(gbc_root, f)
+        if p.exists():
+            p.unlink()
+            deleted.append(str(p))
+
+    for f in sorted(merged_folders):
+        order_source = None
+        if f in disk_folders and _doc_path(gbc_root, f).exists():
+            order_source = read_doc(gbc_root, f)
+        disk_doc = _render_doc(disk_flat, f, order_source) if f in disk_folders else gf.ParsedDoc()
+        target_doc = _render_doc(merged_flat, f, order_source)
+        if not _docs_equal(disk_doc, target_doc):
+            text = gf.serialize(target_doc.intent, target_doc.constraints, target_doc.entries)
+            _write_doc_atomic(gbc_root, f, text)
+            written.append(str(_doc_path(gbc_root, f)))
+
+    return written, deleted
+
+
+_FOLDER_FIELDS = ("intent", "constraints")
+_FILE_FIELDS = ("desc",)
+
+
+def _fields_for_kind(kind: str) -> tuple[str, ...]:
+    return _FOLDER_FIELDS if kind == "folder" else _FILE_FIELDS
+
+
+def _merge_path_fields(path: str, base_node: dict, disk_node: dict, current_node: dict,
+                       force: bool, conflicts: list[dict]) -> tuple[dict | None, bool]:
+    """三方都存在且 kind 相同的节点:逐字段三方合并。返回 (最终节点, 是否冲突)。
+
+    file 仅 desc;folder 为 intent/constraints。用户字段未改→取 disk;仅用户改→current;
+    仅外部改→disk;双方改到相同值→该值;双方改到不同值→冲突字段(force 时取 current)。
+    """
+    fields = _fields_for_kind(base_node.get("kind"))
+    merged = dict(current_node)
+    conflict_fields: list[str] = []
+    for f in fields:
+        b = base_node.get(f, "")
+        d = disk_node.get(f, "")
+        c = current_node.get(f, "")
+        if c == b:
+            merged[f] = d          # 用户未改该字段 → 保留外部(disk)值
+        elif d == b:
+            merged[f] = c          # 仅用户改 → current
+        elif c == d:
+            merged[f] = c          # 双方改到相同值 → 该值
+        else:
+            conflict_fields.append(f)
+            merged[f] = c if force else d
+    if conflict_fields and not force:
+        conflicts.append({"path": path, "fields": conflict_fields,
+                          "disk": disk_node, "user": current_node})
+        return None, True
+    return merged, False
+
+
+def _merge_path(path: str, base_node, disk_node, current_node, force: bool,
+                conflicts: list[dict]) -> tuple[dict | None, bool]:
+    """单路径三方合并。返回 (最终节点或 None=删除, 是否冲突)。
+
+    节点新增/删除/type change 按整节点冲突;三方都存在且 kind 相同才走字段级合并。
+    """
+    base_present = base_node is not None
+    disk_present = disk_node is not None
+    current_present = current_node is not None
+
+    if not base_present:
+        # 新增语义
+        if not disk_present and not current_present:
+            return None, False
+        if disk_present and not current_present:
+            return disk_node, False
+        if current_present and not disk_present:
+            return current_node, False
+        if _node_eq(disk_node, current_node):
+            return current_node, False
+        conflicts.append({"path": path, "disk": disk_node, "user": current_node})
+        return (current_node if force else disk_node), True
+
+    # base 存在:先处理删除
+    if not disk_present and not current_present:
+        return None, False                                   # 双方都删 → 删除
+    if not disk_present:                                     # 外部删、用户保留
+        if not _node_eq(current_node, base_node):
+            conflicts.append({"path": path, "disk": disk_node, "user": current_node})
+            return (current_node if force else None), True
+        return None, False                                   # 用户没改 → 外部删除生效
+    if not current_present:                                  # 用户删、外部保留
+        if not _node_eq(disk_node, base_node):
+            conflicts.append({"path": path, "disk": disk_node, "user": current_node})
+            return (None if force else disk_node), True
+        return None, False                                   # 外部没改 → 用户删除生效
+
+    # 双方都在:类型变化 → 整节点
+    base_kind = base_node.get("kind")
+    if disk_node.get("kind") != base_kind or current_node.get("kind") != base_kind:
+        if _node_eq(disk_node, current_node):
+            return current_node, False
+        conflicts.append({"path": path, "disk": disk_node, "user": current_node})
+        return (current_node if force else disk_node), True
+
+    return _merge_path_fields(path, base_node, disk_node, current_node, force, conflicts)
+
+
+def save_flat(gbc_root: Path, base_flat: dict, current_flat: dict, force: bool = False) -> dict:
+    """冲突感知的选择性保存(字段级三方合并)。
+
+    重新读盘比较 external=base vs disk、user=base vs current:
+    - 节点新增/删除/type change 按整节点冲突;
+    - 三方都存在且 kind 相同:逐字段三方合并(file 仅 desc;folder 为 intent/constraints)。
+    无冲突:以 disk 为合并基线只应用 user 改动,保留不相关外部变动,只重写内容变化的 gbc.md。
+    force 仅覆盖冲突字段/冲突节点。返回 {"written", "deleted", "count"};冲突且 !force 抛
+    IntentConflictError。
+    """
+    _validate_flat(base_flat)
+    _validate_flat(current_flat)
+
+    with _lock_for(str(gbc_root)):
+        gbc_root.mkdir(parents=True, exist_ok=True)
+        disk_flat = read_flat(gbc_root)
+
+        all_paths = set(base_flat) | set(disk_flat) | set(current_flat)
+        conflicts: list[dict] = []
+        external_changes: list[str] = []
+        merged: dict = {}
+        for path in all_paths:
+            base_node = base_flat.get(path)
+            disk_node = disk_flat.get(path)
+            current_node = current_flat.get(path)
+            if not _node_eq(disk_node, base_node):
+                external_changes.append(path)
+            final, _ = _merge_path(path, base_node, disk_node, current_node, force, conflicts)
+            if final is not None:
+                merged[path] = final
+        # 根节点永不可删
+        merged.setdefault("", {"kind": "folder", "intent": "", "constraints": ""})
+
+        if conflicts and not force:
+            raise IntentConflictError(conflicts, external_changes)
+
+        written, deleted = _apply_flat(gbc_root, disk_flat, merged)
+    return {"written": written, "deleted": deleted, "count": len(written)}