excel-codegen 0.9.0__py3-none-any.whl

excel_codegen/derived.py

@@ -0,0 +1,465 @@
+"""派生参数（``derived:``）：让一个参数直接引用**同 Case 的其他参数**与**全局参数**。
+
+用途
+----
+* 中间量：``h_de = k_c * h_di``，模板里直接 ``{{ h_de }}``，不用把这行算式写进模板；
+* 需要"看得到数值"的换算结果：参数表里就能读出它，不必等生成完代码再看；
+* 链式：派生参数可以引用派生参数（``a -> b -> c``），工具按依赖顺序求值。
+
+限制（**只按需求做这两条**）
+--------------------------
+* 只能引用 ``global`` 与**同一个 Case** 的 ``local``；不跨 Case、不跨工作簿；
+* ``global`` 的派生参数不能引用 ``local``（那时还没有"当前 Case"这个概念）。
+
+两条路径，一套语义
+------------------
+* **Python 侧**（快照渲染 / 导出文件 / 指纹）：用 ``jinja_env`` 的环境求值，拿真正的值；
+* **Excel 侧**（参数表里那一格）：能翻译成 Excel 公式的就写公式（改输入自动重算），
+  翻译不了（用了 ``|`` 过滤器里没有对应的、条件表达式以外的花活……）就把算好的值写进去，
+  并告警"改输入后需要重跑 --write-excel"。
+
+翻译覆盖的子集：``+ - * / **``、``%``（-> ``MOD``）、``~``（-> ``&``，字符串拼接）、
+括号、数字/字符串/布尔常量、变量、``min/max/abs/round/int/float``、
+``|round|abs|int|float``、比较运算、``and/or/not``、条件表达式（-> ``IF``）。
+其余一律报错（不猜），由调用方降级。
+"""
+
+from __future__ import annotations
+
+from collections.abc import Iterable, Mapping, MutableMapping, Sequence
+from typing import Any
+
+from jinja2 import Environment, TemplateError, TemplateSyntaxError, UndefinedError, meta, nodes
+
+from .jinja_env import build_environment
+from .models import ProjectConfig, VariableDef
+from .utils import RenderError, to_text
+
+__all__ = [
+    "DerivedError",
+    "DerivedNotTranslatable",
+    "derived_variables",
+    "evaluate_derived",
+    "expression_names",
+    "is_derived",
+    "is_translatable",
+    "ordered_derived",
+    "to_excel",
+    "untranslatable_names",
+    "validate_config",
+]
+
+
+class DerivedError(RenderError):
+    """派生参数写得不对：语法错、引用越界、循环引用、类型不对……"""
+
+
+class DerivedNotTranslatable(DerivedError):
+    """表达式本身没错，但超出"能翻译成 Excel 公式"的子集。
+
+    与 :class:`DerivedError` 分开，是为了让调用方**只**对这种情况降级
+    （往格子里写算好的值），而不是把语法错误也静默吞掉。
+    """
+
+
+def is_derived(variable: VariableDef) -> bool:
+    return bool(variable.derived)
+
+
+def derived_variables(variables: Iterable[VariableDef]) -> list[VariableDef]:
+    return [variable for variable in variables if is_derived(variable)]
+
+
+# --------------------------------------------------------------------------- #
+# 表达式：名字与顺序
+# --------------------------------------------------------------------------- #
+def expression_names(expression: str, *, env: Environment | None = None) -> set[str]:
+    """表达式里引用到的变量名。"""
+    environment = env or build_environment()
+    try:
+        ast = environment.parse("{{ " + expression + " }}")
+    except TemplateSyntaxError as exc:
+        raise DerivedError(f"派生表达式语法错误（第 {exc.lineno} 行）：{exc.message}；表达式：{expression!r}") from exc
+    return set(meta.find_undeclared_variables(ast))
+
+
+def ordered_derived(
+    variables: Sequence[VariableDef],
+    *,
+    scope: str,
+    env: Environment | None = None,
+) -> list[VariableDef]:
+    """按依赖顺序排列派生参数；有环就报错（带上环上的名字）。"""
+    environment = env or build_environment()
+    derived = {variable.name: variable for variable in derived_variables(variables)}
+    if not derived:
+        return []
+
+    deps = {
+        name: expression_names(variable.derived or "", env=environment) & derived.keys()
+        for name, variable in derived.items()
+    }
+
+    ordered: list[VariableDef] = []
+    done: set[str] = set()
+    while len(ordered) < len(derived):
+        ready = [name for name in derived if name not in done and deps[name] <= done]
+        if not ready:
+            cycle = _find_cycle(deps)
+            raise DerivedError(
+                f"{scope} 的派生参数存在循环引用：{' -> '.join(cycle)}；"
+                "派生参数只能引用同 Case 的其他参数与全局参数，不能互相依赖成环"
+            )
+        for name in sorted(ready):
+            ordered.append(derived[name])
+            done.add(name)
+    return ordered
+
+
+def _find_cycle(deps: Mapping[str, set[str]]) -> list[str]:
+    """从依赖图里挑出一个环，用于报错信息。"""
+    visiting: list[str] = []
+    seen: set[str] = set()
+
+    def walk(node: str) -> list[str] | None:
+        if node in visiting:
+            return [*visiting[visiting.index(node) :], node]
+        if node in seen:
+            return None
+        visiting.append(node)
+        for dep in sorted(deps.get(node, ())):
+            found = walk(dep)
+            if found:
+                return found
+        visiting.pop()
+        seen.add(node)
+        return None
+
+    for name in sorted(deps):
+        found = walk(name)
+        if found:
+            return found
+    return ["<未知>"]
+
+
+# --------------------------------------------------------------------------- #
+# 求值（Python 侧）
+# --------------------------------------------------------------------------- #
+def evaluate_derived(
+    variables: Sequence[VariableDef],
+    context: MutableMapping[str, Any],
+    *,
+    scope: str,
+    env: Environment | None = None,
+    forbidden: Mapping[str, str] | None = None,
+) -> None:
+    """按依赖顺序求值派生参数，结果写进 ``context``（原地更新）。
+
+    :param scope: 出错信息里用的作用域描述，例如 ``"global"`` / ``"Case1 的 local"``
+    :param forbidden: ``{变量名: 说明}``；表达式引用到这些名字就报错
+        （用来实现"global 派生参数不能引用 local 变量"）
+    """
+    environment = env or build_environment()
+    forbidden = forbidden or {}
+    for variable in ordered_derived(variables, scope=scope, env=environment):
+        expression = variable.derived or ""
+        for name in sorted(expression_names(expression, env=environment)):
+            if name in forbidden:
+                raise DerivedError(
+                    f"派生参数 {variable.name!r}（{scope}）引用了 {name!r}：{forbidden[name]}；表达式：{expression!r}"
+                )
+        context[variable.name] = _evaluate(expression, context, env=environment, variable=variable)
+
+
+def _evaluate(
+    expression: str,
+    context: Mapping[str, Any],
+    *,
+    env: Environment,
+    variable: VariableDef,
+) -> Any:
+    try:
+        compiled = env.compile_expression(expression, undefined_to_none=False)
+    except TemplateSyntaxError as exc:
+        raise DerivedError(
+            f"派生参数 {variable.name!r} 的表达式语法错误（第 {exc.lineno} 行）：{exc.message}；表达式：{expression!r}"
+        ) from exc
+    try:
+        return compiled(**context)
+    except UndefinedError as exc:
+        raise DerivedError(
+            f"派生参数 {variable.name!r} 引用了取不到的变量：{exc.message or exc}；"
+            f"表达式：{expression!r}"
+            "（派生参数只能引用 YAML 里定义的 global / 同 Case 的 local）"
+        ) from exc
+    except TemplateError as exc:
+        raise DerivedError(f"派生参数 {variable.name!r} 求值失败：{exc}；表达式：{expression!r}") from exc
+    except Exception as exc:
+        raise DerivedError(
+            f"派生参数 {variable.name!r} 求值失败：{type(exc).__name__}: {exc}；表达式：{expression!r}"
+        ) from exc
+
+
+# --------------------------------------------------------------------------- #
+# 翻译成 Excel 公式
+# --------------------------------------------------------------------------- #
+_BINOPS = {"+": "+", "-": "-", "*": "*", "/": "/", "**": "^"}
+#: Jinja 的比较运算用的是名字（gt / lteq …），不是符号
+_COMPARE = {
+    "eq": "=",
+    "ne": "<>",
+    "gt": ">",
+    "lt": "<",
+    "gteq": ">=",
+    "lteq": "<=",
+    "==": "=",
+    "!=": "<>",
+    ">=": ">=",
+    "<=": "<=",
+    ">": ">",
+    "<": "<",
+}
+#: 表达式里的函数 -> Excel 函数。``int`` 用 ``TRUNC``：Python 的 ``int()`` 向零截断，
+#: 而 Excel 的 ``INT()`` 是向下取整（``int(-2.5)`` 在两边会差 1）。
+_FUNCS = {"min": "MIN", "max": "MAX", "abs": "ABS", "int": "TRUNC", "float": None}
+_FILTERS = {"abs": "ABS", "int": "TRUNC", "float": None, "string": None}
+
+#: 两种语言语义不同的运算：**故意不翻译**（翻译了就会"Excel 里看到的"与"导出的"不一致）
+_NOT_TRANSLATABLE = {
+    "round": "Python 的 round() 是银行家舍入（round(2.5) == 2），Excel 的 ROUND() 是四舍五入（2.5 -> 3）",
+    "ceil": "Python 的 ceil() 与 Excel 的 CEILING 边界行为不同",
+    "floor": "Python 的 floor() 与 Excel 的 FLOOR 边界行为不同（负数）",
+}
+
+
+def to_excel(
+    expression: str,
+    *,
+    name: str,
+    resolve,
+    env: Environment | None = None,
+    condition: bool = False,
+) -> str:
+    """把派生表达式翻译成 Excel 公式（不带前导 ``=``）。
+
+    :param resolve: ``变量名 -> Excel 引用`` 的回调（由调用方决定列/表名与相对/绝对）
+    :param condition: 这是不是一个**条件**表达式。为 ``True`` 时 ``and`` / ``or`` / ``not``
+        可以翻译成 ``AND`` / ``OR`` / ``NOT``（Python 的 ``and``/``or`` 有返回值语义，
+        与 Excel 不同，所以只在条件位置放行）。公式模式的行内 ``{% if %}`` 走这条路。
+    :raises DerivedError: 表达式超出可翻译子集（调用方应当降级为"写入算好的值"）
+    """
+    environment = env or build_environment()
+    try:
+        ast = environment.parse("{{ " + expression + " }}")
+    except TemplateSyntaxError as exc:
+        raise DerivedError(f"派生参数 {name!r} 的表达式语法错误：{exc.message}；表达式：{expression!r}") from exc
+    body = getattr(ast, "body", [])
+    if len(body) != 1 or not isinstance(body[0], nodes.Output) or len(body[0].nodes) != 1:
+        raise DerivedError(f"派生参数 {name!r} 的表达式不是单个表达式：{expression!r}")
+    return _translate(body[0].nodes[0], name=name, resolve=resolve, env=environment, condition=condition)
+
+
+def _translate(node, *, name: str, resolve, env: Environment, condition: bool) -> str:
+    if isinstance(node, nodes.Const):
+        return _excel_literal(node.value)
+    if isinstance(node, nodes.Name):
+        return resolve(node.name)
+    if isinstance(node, nodes.Getattr):
+        # 属性访问（``x.value`` / ``x.prefix`` …）：把属性名一并交给调用方 —— 只有它知道
+        # 该怎么把一个"取值 / 前缀"映射成单元格引用。老的回调只收一个参数，用 TypeError 兜住。
+        inner = node.node
+        if not isinstance(inner, nodes.Name):
+            raise DerivedNotTranslatable(f"表达式 {name!r} 里的 .{node.attr} 只能接在变量名后面")
+        try:
+            return resolve(inner.name, node.attr)
+        except TypeError as exc:
+            raise DerivedNotTranslatable(
+                f"表达式 {name!r} 里用了属性访问 .{node.attr}，但当前上下文不支持"
+                "（属性访问只在公式模式的行内 {% if %} 条件里可用）"
+            ) from exc
+    if isinstance(node, nodes.Concat):
+        return "&".join(
+            f"({_translate(item, name=name, resolve=resolve, env=env, condition=False)})" for item in node.nodes
+        )
+    # ⚠ and / or 必须排在 BinExpr **前面**：jinja2 里 ``And`` / ``Or`` 是 ``BinExpr`` 的子类，
+    # 先命中 BinExpr 分支的话它们会被当成"不支持的运算符"（这段曾经是死代码，见 0.6.0 修复）。
+    if isinstance(node, (nodes.And, nodes.Or)):
+        if not condition:
+            raise DerivedNotTranslatable(
+                f"派生参数 {name!r} 的 and/or 只能用在条件表达式里"
+                "（Python 的 and/or 返回值语义与 Excel 不同，避免静默偏差）"
+            )
+        function = "AND" if isinstance(node, nodes.And) else "OR"
+        left = _translate(node.left, name=name, resolve=resolve, env=env, condition=True)
+        right = _translate(node.right, name=name, resolve=resolve, env=env, condition=True)
+        return f"{function}({left},{right})"
+    if isinstance(node, nodes.BinExpr):
+        operator = getattr(node, "operator", None)
+        left = _translate(node.left, name=name, resolve=resolve, env=env, condition=False)
+        right = _translate(node.right, name=name, resolve=resolve, env=env, condition=False)
+        if operator == "%":
+            return f"MOD({left},{right})"
+        if operator == "//":
+            raise DerivedNotTranslatable(f"派生参数 {name!r} 用了 //（整除）：Excel 没有等价运算，请改用 / 或 round()")
+        if operator not in _BINOPS:
+            raise DerivedNotTranslatable(f"派生参数 {name!r} 用了不支持的运算符 {operator!r}")
+        return f"({left}{_BINOPS[operator]}{right})"
+    if isinstance(node, nodes.Neg):
+        return f"-({_translate(node.node, name=name, resolve=resolve, env=env, condition=False)})"
+    if isinstance(node, nodes.Pos):
+        return f"({_translate(node.node, name=name, resolve=resolve, env=env, condition=False)})"
+    if isinstance(node, nodes.Not):
+        if not condition:
+            raise DerivedNotTranslatable(f"派生参数 {name!r} 的 not 只能用在条件表达式里")
+        inner_excel = _translate(node.node, name=name, resolve=resolve, env=env, condition=True)
+        return f"NOT({inner_excel})"
+    if isinstance(node, nodes.Compare):
+        return _translate_compare(node, name=name, resolve=resolve, env=env)
+    if isinstance(node, nodes.CondExpr):
+        test = _translate(node.test, name=name, resolve=resolve, env=env, condition=True)
+        yes = _translate(node.expr1, name=name, resolve=resolve, env=env, condition=False)
+        no = _translate(node.expr2, name=name, resolve=resolve, env=env, condition=False)
+        return f"IF({test},{yes},{no})"
+    if isinstance(node, nodes.Filter):
+        return _translate_filter(node, name=name, resolve=resolve, env=env)
+    if isinstance(node, nodes.Call):
+        return _translate_call(node, name=name, resolve=resolve, env=env)
+    raise DerivedNotTranslatable(
+        f"派生参数 {name!r} 的表达式超出可翻译范围（{type(node).__name__}）："
+        "能翻译的子集见 docs/template_guide.md §15；"
+        "也可以让它留在 Python 侧（表里写入算好的值，改输入后重跑 --write-excel）"
+    )
+
+
+def _translate_compare(node, *, name: str, resolve, env: Environment) -> str:
+    parts: list[str] = []
+    left = _translate(node.expr, name=name, resolve=resolve, env=env, condition=False)
+    for operand in node.ops:
+        operator = getattr(operand, "op", None)
+        right = _translate(operand.expr, name=name, resolve=resolve, env=env, condition=False)
+        if operator not in _COMPARE:
+            raise DerivedNotTranslatable(f"派生参数 {name!r} 用了不支持的比较运算 {operator!r}")
+        parts.append(f"({left}{_COMPARE[operator]}{right})")
+        left = right
+    return parts[0] if len(parts) == 1 else "AND(" + ",".join(parts) + ")"
+
+
+def _translate_filter(node, *, name: str, resolve, env: Environment) -> str:
+    if node.dyn_args is not None or node.dyn_kwargs is not None:
+        raise DerivedNotTranslatable(f"派生参数 {name!r} 的过滤器用了动态参数，无法翻译")
+    if node.name in _NOT_TRANSLATABLE:
+        raise DerivedNotTranslatable(
+            f"派生参数 {name!r} 用了 |{node.name}：{_NOT_TRANSLATABLE[node.name]}，"
+            "所以不往 Excel 公式翻译（表里会写入 Python 算好的值）"
+        )
+    function = _FILTERS.get(node.name)
+    if function is None and node.name not in _FILTERS:
+        raise DerivedNotTranslatable(f"派生参数 {name!r} 用了过滤器 |{node.name}，Excel 侧没有对应函数")
+    value = _translate(node.node, name=name, resolve=resolve, env=env, condition=False)
+    if function is None:  # float / string：Excel 里就是原值
+        return f"({value})"
+    return f"{function}({value})"
+
+
+def _translate_call(node, *, name: str, resolve, env: Environment) -> str:
+    if not isinstance(node.node, nodes.Name):
+        raise DerivedNotTranslatable(f"派生参数 {name!r} 调用了非函数对象，无法翻译")
+    if node.kwargs and any(kw.key for kw in node.kwargs):
+        raise DerivedNotTranslatable(f"派生参数 {name!r} 的函数用了关键字参数，无法翻译")
+    if node.dyn_args is not None or node.dyn_kwargs is not None:
+        raise DerivedNotTranslatable(f"派生参数 {name!r} 的函数用了 *args/**kwargs，无法翻译")
+
+    function_name = node.node.name
+    if function_name in _NOT_TRANSLATABLE:
+        raise DerivedNotTranslatable(
+            f"派生参数 {name!r} 用了 {function_name}()：{_NOT_TRANSLATABLE[function_name]}，"
+            "所以不往 Excel 公式翻译（表里会写入 Python 算好的值）"
+        )
+    if function_name not in _FUNCS:
+        raise DerivedNotTranslatable(
+            f"派生参数 {name!r} 调用了 {function_name}()，Excel 侧没有对应函数（支持 min/max/abs/int/float）"
+        )
+    arguments = [_translate(argument, name=name, resolve=resolve, env=env, condition=False) for argument in node.args]
+    excel_function = _FUNCS[function_name]
+    if excel_function is None:  # float()：Excel 里数字就是数字
+        if len(arguments) != 1:
+            raise DerivedNotTranslatable(f"派生参数 {name!r} 的 {function_name}() 只支持一个参数")
+        return f"({arguments[0]})"
+    if not arguments:
+        raise DerivedNotTranslatable(f"派生参数 {name!r} 的 {function_name}() 缺参数")
+    return f"{excel_function}({','.join(arguments)})"
+
+
+def _excel_literal(value: Any) -> str:
+    if isinstance(value, bool):
+        return "TRUE" if value else "FALSE"
+    if isinstance(value, (int, float)):
+        return repr(value)
+    text = to_text(value)
+    return '"' + text.replace('"', '""') + '"'
+
+
+def is_translatable(variable: VariableDef, *, env: Environment | None = None) -> bool:
+    """这个派生表达式能不能写成 Excel 公式（不能就只能往格子里写算好的值）。"""
+    if not is_derived(variable):
+        return True
+    try:
+        to_excel(variable.derived or "", name=variable.name, resolve=lambda _: "A1", env=env)
+        return True
+    except DerivedNotTranslatable:
+        return False
+
+
+def untranslatable_names(config: ProjectConfig, *, env: Environment | None = None) -> list[str]:
+    """哪些派生参数翻译不成 Excel 公式（表里只能写入算好的值）。"""
+    environment = env or build_environment()
+    return [
+        variable.name
+        for variable in [*config.global_variables, *config.local_variables]
+        if is_derived(variable) and not is_translatable(variable, env=environment)
+    ]
+
+
+def validate_config(config: ProjectConfig, *, env: Environment | None = None) -> list[str]:
+    """配置期的派生参数检查：语法、引用范围、循环；返回警告（不能翻译成 Excel 公式的）。
+
+    :raises DerivedError: 表达式语法错 / 引用了不该引用的名字 / 循环引用 / 引用了未定义的名字
+    """
+    environment = env or build_environment()
+    global_names = set(config.global_names)
+    local_names = set(config.local_names)
+    known = global_names | local_names
+
+    for variable in derived_variables(config.global_variables):
+        for name in sorted(expression_names(variable.derived or "", env=environment)):
+            if name in local_names:
+                raise DerivedError(
+                    f"派生参数 {variable.name!r}（global）引用了 local 变量 {name!r}："
+                    "global 的派生参数不能引用 local 变量（那时还没有当前 Case）"
+                )
+            if name not in known:
+                raise DerivedError(
+                    f"派生参数 {variable.name!r}（global）引用了未定义的变量 {name!r}；"
+                    "派生参数只能引用 YAML 里定义的 global / 同 Case 的 local"
+                )
+
+    for variable in derived_variables(config.local_variables):
+        for name in sorted(expression_names(variable.derived or "", env=environment)):
+            if name not in known:
+                raise DerivedError(
+                    f"派生参数 {variable.name!r}（local）引用了未定义的变量 {name!r}；"
+                    "派生参数只能引用 YAML 里定义的 global / 同 Case 的 local"
+                )
+
+    ordered_derived(config.global_variables, scope="global 的派生参数", env=environment)
+    ordered_derived(config.local_variables, scope="local 的派生参数", env=environment)
+
+    untranslatable = untranslatable_names(config, env=environment)
+    return (
+        [
+            "这些派生参数写不成 Excel 公式，参数表里只能写入算好的值"
+            f"（改输入后要重跑 --write-excel 刷新）：{', '.join(untranslatable)}"
+        ]
+        if untranslatable
+        else []
+    )

excel_codegen/example_pack.py

@@ -0,0 +1,107 @@
+"""随包发布的内置示例（``excel_codegen/examples/``）：定位、列出、复制。
+
+示例是**包数据** —— wheel 与 sdist 里都有一份，所以 ``pip install excel-codegen`` /
+``uv tool install excel-codegen`` 装完、没有克隆仓库的人也能拿到：
+
+    excel-codegen examples                  # 看有哪些示例、各自演示什么
+    excel-codegen examples --copy ./demo    # 拷出来直接用
+
+它同时是仓库里的回归夹具（``abs_fpi/`` 的现场脚本与 ``tests/`` 都直接读这几个 YAML），
+所以仓库根目录**不再**单独放一份 ``examples/``，免得两份漂移。
+"""
+
+from __future__ import annotations
+
+import shutil
+from dataclasses import dataclass
+from pathlib import Path
+
+from .utils import CodeGenError
+
+__all__ = ["EXAMPLES", "Example", "copy_examples", "examples_root"]
+
+
+@dataclass(frozen=True)
+class Example:
+    """一个内置示例：目录名 + 给人看的说明 + 两个常用路径（都相对示例根目录）。"""
+
+    name: str
+    title: str
+    summary: str
+    entry: str
+    workbook: str
+
+
+#: 示例清单。新增一个示例 = 在 ``examples/<name>/`` 放好文件 + 在这里登记；
+#: ``tests/test_examples_command.py`` 会检查两边一一对应，漏登记会红。
+EXAMPLES: tuple[Example, ...] = (
+    Example(
+        name="basic",
+        title="入门：公式模式与快照模式",
+        summary=(
+            "STM32 风格的 UART 配置。example_formula.yaml 是默认的公式模式"
+            "（改参数在 Excel 里自己重算，不用跑命令）；example.yaml 显式写 engine: snapshot，"
+            "演示过滤器 / 循环 / 导出文件。"
+        ),
+        entry="basic/example_formula.yaml",
+        workbook="basic/template_formula.xlsx",
+    ),
+    Example(
+        name="nastran",
+        title="NASTRAN 工况控制：一行一个工况",
+        summary=(
+            "local_direction: vertical —— Local 表一行一个工况，下拉即增行；"
+            "语句留空就不输出，最后拼成 .inc / .deck 工况控制语句（指南 §19 / §20）。"
+        ),
+        entry="nastran/nastran_case_control.yaml",
+        workbook="nastran/nastran_case_control.xlsx",
+    ),
+    Example(
+        name="abs_fpi",
+        title="现场用例：ABS FPI 内外压 → GeniE",
+        summary=(
+            "两个规则集（外压 5A-3-2/5.5、内压 5A-3-2/5.7）可以各自单独生成一本工作簿，"
+            "也可以合成一本项目工作簿共用一张 Global 表；内压用成员表 Tank Data 把舱参数只写一遍。"
+        ),
+        entry="abs_fpi/abs_fpi_internal.yaml",
+        workbook="abs_fpi/abs_fpi_internal.xlsx",
+    ),
+)
+
+
+def examples_root() -> Path:
+    """内置示例的根目录（可编辑安装与 wheel 安装都在同一个相对位置）。"""
+    return Path(__file__).resolve().parent / "examples"
+
+
+def find(name: str) -> Example:
+    for example in EXAMPLES:
+        if example.name == name:
+            return example
+    available = "、".join(item.name for item in EXAMPLES)
+    raise CodeGenError(f"没有这个示例：{name}（可选：{available}）")
+
+
+def copy_examples(dest: Path, *, only: str | None = None, force: bool = False) -> list[Path]:
+    """把示例拷进 ``dest/<示例名>/``，返回拷出来的顶层目录列表。
+
+    :param only: 只拷这一个（默认全部）。
+    :param force: 目标目录已存在且非空时是否覆盖。
+    """
+    selected = (find(only),) if only else EXAMPLES
+    root = examples_root()
+    if not root.is_dir():  # pragma: no cover - 只有被裁剪过的安装才会走到
+        raise CodeGenError(f"找不到内置示例目录：{root}（安装包可能不完整，重装一次试试）")
+
+    dest.mkdir(parents=True, exist_ok=True)
+    written: list[Path] = []
+    for example in selected:
+        src = root / example.name
+        if not src.is_dir():  # pragma: no cover - 由 tests/test_examples_command.py 守住
+            raise CodeGenError(f"内置示例 {example.name} 缺文件：{src}")
+        target = dest / example.name
+        if target.exists() and any(target.iterdir()) and not force:
+            raise CodeGenError(f"{target} 已存在且非空：加 --force 覆盖，或换一个目录")
+        shutil.copytree(src, target, dirs_exist_ok=True)
+        written.append(target)
+    return written

excel_codegen/examples/README.md

@@ -0,0 +1,69 @@
+# 内置示例
+
+示例**随包发布**（wheel 与 sdist 里都有），所以装了 `excel-codegen` 就够了，
+不需要克隆仓库：
+
+```bash
+excel-codegen examples                     # 列出示例、各自演示什么
+excel-codegen examples --copy ./examples   # 拷到 ./examples（--only abs_fpi 只拷一个）
+```
+
+拷出来之后**打开里面的 `.xlsx` 就能改** —— 每一本都已经填好样例数值，而且默认是
+**公式模式**：改一格参数，`Output` 表里的代码自己就重算，不需要跑任何命令。
+要让「导出的代码文件」跟着更新，才需要回到命令行（或双击同目录的 `*_render.bat` / 跑 `*_render.sh`）。
+
+| 示例 | 入口 YAML | 工作簿 | 演示什么 |
+| --- | --- | --- | --- |
+| [`basic/`](basic/) | `example_formula.yaml` | `template_formula.xlsx` | **默认的公式模式**：改参数在 Excel 里自动重算 |
+| | `example.yaml` | `template.xlsx` | 显式 `engine: snapshot`：过滤器 / 循环 / 导出文件 |
+| [`nastran/`](nastran/) | `nastran_case_control.yaml` | `nastran_case_control.xlsx` | **一行一个工况**（`local_direction: vertical`）生成工况控制语句（指南 §19 / §20） |
+| [`abs_fpi/`](abs_fpi/) | `abs_fpi_internal.yaml` | `abs_fpi_internal.xlsx` | **现场用例**：ABS FPI 内外压 → GeniE；多规则集 / 成员表（指南 §18） |
+
+> `generated*/` 里的文件是**提交进仓库的实测产物**（脚本导出一次的结果），
+> 拿它跟你自己跑出来的对一下，就知道有没有改坏。
+
+---
+
+## basic —— 入门：公式模式与快照模式
+
+```bash
+cd basic
+
+# 工作簿已经生成好了，直接打开 template_formula.xlsx 改参数即可。
+# 要把代码导成文件：
+excel-codegen render -c example_formula.yaml -x template_formula.xlsx --outdir generated_formula
+
+# 核对「Excel 里算出来的」与「Python 渲染的」是否一致（CI 里很有用）：
+excel-codegen check -c example_formula.yaml -x template_formula.xlsx
+```
+
+`example.yaml` 是**对照示例**：它显式写 `engine: snapshot`，用到了公式模式表达不了的
+`{% for %}` 与过滤器，同时演示 `filename` 导出多个文件。两条路的取舍见指南 §14。
+
+## nastran —— 一行一个工况
+
+```bash
+cd nastran
+excel-codegen render -c nastran_case_control.yaml -x nastran_case_control.xlsx --outdir generated
+```
+
+Local 表是**竖着**的（`local_direction: vertical`）：一行一个工况，下拉即增行，
+整块从别处粘进来也方便。每条语句**留空就不输出**，而它在表里占的那一行仍然是空的
+（方便整列复制）。输出是 `.inc` / `.deck` 工况控制语句，外加每块的摘要。
+
+## abs_fpi —— 现场用例：ABS FPI 内外压 → GeniE
+
+把 **ABS FPI**（5A-3-2/5.5 外压、5.7 内压）的面载荷计算，生成可直接粘进 GeniE 的
+JavaScript 函数体。详见 [`abs_fpi/README.md`](abs_fpi/README.md)。
+
+```bash
+cd abs_fpi
+
+# 三本工作簿，挑一本打开就能改：
+#   abs_fpi_external.xlsx     外压单用（3 个工况）
+#   abs_fpi_internal.xlsx     内压单用（4 个工况）
+#   ABS_FPI_load_cases.xlsx   项目工作簿：两套规则共用一张 Global 表（7 个工况）
+excel-codegen render -c abs_fpi_internal.yaml -x abs_fpi_internal.xlsx --outdir generated
+```
+
+> 用例里的舱容与工况组合只是**示意数值**（随手取的几个数），不代表任何真实船舶。

excel_codegen/examples/abs_fpi/ABS_FPI_load_cases_render.bat

@@ -0,0 +1,22 @@
+@echo off
+REM ===========================================================================
+REM  由 excel_codegen 生成 —— 改完参数双击本文件即可把结果写回 Output 表。
+REM  重新生成工作簿（init）时会一并覆盖本文件。
+REM ===========================================================================
+cd /d "%~dp0"
+
+where uv >nul 2>nul
+if %errorlevel%==0 (
+  uv run excel-codegen render -c "abs_fpi.yaml" -x "ABS_FPI_load_cases.xlsx" --write-excel
+) else (
+  excel-codegen render -c "abs_fpi.yaml" -x "ABS_FPI_load_cases.xlsx" --write-excel
+)
+
+echo.
+if errorlevel 1 (
+  echo [失败] 上面有报错信息。常见原因：依赖没装（跑一次 setup.sh / uv sync）、
+  echo        或者 Excel 正开着这个文件（先关掉再试）。
+) else (
+  echo [完成] 回到 Excel 打开「Output」表看结果。
+)
+pause