godot-cli-control 0.2.10__tar.gz → 0.2.12__tar.gz

{godot_cli_control-0.2.10 → godot_cli_control-0.2.12}/PKG-INFO

@@ -1,6 +1,6 @@
 Metadata-Version: 2.4
 Name: godot-cli-control
-Version: 0.2.10
+Version: 0.2.12
 Summary: WebSocket bridge for headless / scripted control of Godot scenes.
 Author: kesar
 License: MIT
@@ -114,7 +114,8 @@ The CLI is the canonical surface — every `GameClient` method has a one-line eq
 ```bash
 # Lifecycle
 godot-cli-control init [--path DIR] [--force]
-godot-cli-control daemon start [--headless --record --movie-path X --fps N --port N --idle-timeout 30m]
+godot-cli-control daemon start [--headless | --gui] [--port N --idle-timeout 30m]
+godot-cli-control daemon start --record --movie-path X [--fps N]   # 录制需真实渲染器，不能与 --headless 同用
 godot-cli-control daemon stop [--all | --project PATH]
 godot-cli-control daemon status
 godot-cli-control daemon ls                  # list running daemons across all projects

{godot_cli_control-0.2.10 → godot_cli_control-0.2.12}/addons/godot_cli_control/README.md

@@ -9,13 +9,13 @@ If you have the Python CLI installed (`pipx install godot-cli-control`), the ent
 
 ```bash
 cd your_godot_project
-godot-cli-control init        # copy plugin, patch project.godot, detect Godot
+godot-cli-control init        # copy plugin, patch project.godot, detect Godot, gitignore .cli_control/
 godot-cli-control daemon start
 godot-cli-control tree 3
 godot-cli-control daemon stop
 ```
 
-`init` automates everything described in the manual setup below — copying the addon, editing `project.godot`, and detecting your Godot binary.
+`init` automates everything described in the manual setup below — copying the addon, editing `project.godot`, and detecting your Godot binary. It also appends `.cli_control/` to the project's root `.gitignore` (the daemon's machine-local state dir: detected binary path, pid, port, log, recording intermediates), so that state never gets committed. Pass `--no-gitignore` to skip that step.
 
 ## Manual Setup (if you prefer)
 

{godot_cli_control-0.2.10 → godot_cli_control-0.2.12}/python/README.md

@@ -97,7 +97,8 @@ The CLI is the canonical surface — every `GameClient` method has a one-line eq
 ```bash
 # Lifecycle
 godot-cli-control init [--path DIR] [--force]
-godot-cli-control daemon start [--headless --record --movie-path X --fps N --port N --idle-timeout 30m]
+godot-cli-control daemon start [--headless | --gui] [--port N --idle-timeout 30m]
+godot-cli-control daemon start --record --movie-path X [--fps N]   # 录制需真实渲染器，不能与 --headless 同用
 godot-cli-control daemon stop [--all | --project PATH]
 godot-cli-control daemon status
 godot-cli-control daemon ls                  # list running daemons across all projects

{godot_cli_control-0.2.10 → godot_cli_control-0.2.12}/python/godot_cli_control/_version.py

@@ -18,7 +18,7 @@ version_tuple: tuple[int | str, ...]
 commit_id: str | None
 __commit_id__: str | None
 
-__version__ = version = '0.2.10'
-__version_tuple__ = version_tuple = (0, 2, 10)
+__version__ = version = '0.2.12'
+__version_tuple__ = version_tuple = (0, 2, 12)
 
 __commit_id__ = commit_id = None

{godot_cli_control-0.2.10 → godot_cli_control-0.2.12}/python/godot_cli_control/cli.py

@@ -73,11 +73,18 @@ def _resolve_headless(
     True，让没显式指定 ``--headless`` / ``--gui`` 的非 TTY 场景（subagent / pipe）
     自动改走 GUI —— headless 下 dummy renderer 拿不到 viewport texture，screenshot
     永远 1006 fail（issue #65）。
+
+    ``--record`` 同理且更狠：Movie Maker 的 ``add_frame()`` 读的也是 viewport
+    texture，headless 下拿到 null 直接 SIGSEGV（CultivationWorld #180）。所以没显式
+    ``--headless`` 时一律翻成 GUI；显式 ``--headless`` 仍返回 True，由
+    ``daemon.start`` 的 preflight 拒绝（明确用法错，不静默改写用户意图）。
     """
     if getattr(ns, "headless", False):
         return True
     if getattr(ns, "gui", False):
         return False
+    if getattr(ns, "record", False):
+        return False
     if force_gui_hint:
         return False
     try:
@@ -1257,6 +1264,7 @@ def cmd_init(ns: argparse.Namespace) -> int:
             write_skills=not ns.no_skills,
             skills_only=ns.skills_only,
             clobber_skills=not ns.skills_no_clobber,
+            write_gitignore=not ns.no_gitignore,
             output_format=fmt,
             result=result,
         )
@@ -1356,7 +1364,8 @@ def _add_daemon_flags(p: argparse.ArgumentParser) -> None:
     p.add_argument(
         "--record",
         action="store_true",
-        help="启动后录制 demo（写到 .cli_control/movie_path）",
+        help="启动后录制 demo（写到 .cli_control/movie_path）。需真实渲染器，"
+        "不能与 --headless 同用；没指定时会自动开窗（即使非 TTY）。",
     )
     p.add_argument(
         "--movie-path",
@@ -1367,7 +1376,8 @@ def _add_daemon_flags(p: argparse.ArgumentParser) -> None:
     headless_grp.add_argument(
         "--headless",
         action="store_true",
-        help="无窗口模式。默认值：stdout 非 TTY 时自动 headless（CI / pipe / agent）。",
+        help="无窗口模式。默认值：stdout 非 TTY 时自动 headless（CI / pipe / agent）。"
+        "与 --record 互斥（录制需真实渲染器）。",
     )
     headless_grp.add_argument(
         "--gui",
@@ -1560,7 +1570,7 @@ def build_parser() -> argparse.ArgumentParser:
         help="在 Godot 项目根一键接入插件",
         description=(
             "复制 addons/godot_cli_control 到目标项目、patch project.godot 启用插件、"
-            "校验 GODOT_BIN。"
+            "校验 GODOT_BIN、在 .gitignore 忽略 .cli_control/。"
         ),
         epilog=(
             "GODOT_BIN 查找顺序：\n"
@@ -1592,6 +1602,14 @@ def build_parser() -> argparse.ArgumentParser:
             "保证版本与 CLI 帮助同步）。与 --no-skills / --skills-only 都兼容。"
         ),
     )
+    init_p.add_argument(
+        "--no-gitignore",
+        action="store_true",
+        help=(
+            "跳过往项目根 .gitignore 追加 .cli_control/（默认会追加，"
+            "忽略 daemon 的机器本地状态目录）。--skills-only 模式下本就跳过。"
+        ),
+    )
     skills_group = init_p.add_mutually_exclusive_group()
     skills_group.add_argument(
         "--no-skills",

{godot_cli_control-0.2.10 → godot_cli_control-0.2.12}/python/godot_cli_control/daemon.py

@@ -93,6 +93,17 @@ class Daemon:
             )
         if record and not movie_path:
             raise DaemonError("--record requires --movie-path")
+        # 录制无法在 headless 下跑：Godot Movie Maker 的 add_frame() 读 viewport
+        # texture，headless dummy renderer 拿到 null 直接 SIGSEGV（首帧崩，
+        # CultivationWorld #180）。CLI 侧 _resolve_headless 已把「没显式 --headless
+        # 的 record」翻成 GUI，所以走到这里还 headless=True 的只可能是用户显式
+        # --headless —— 这是用法矛盾，spawn 前拒绝，别让 Godot 段错误。
+        if record and headless:
+            raise DaemonError(
+                "录制与 --headless 冲突：Godot Movie Maker 需要真实渲染器，"
+                "headless dummy renderer 拿不到 viewport texture，add_frame() 会"
+                " SIGSEGV。去掉 --headless（默认/非 TTY 会自动开窗）或显式 --gui。"
+            )
 
         bin_path = (
             godot_bin

{godot_cli_control-0.2.10 → godot_cli_control-0.2.12}/python/godot_cli_control/init_cmd.py

@@ -8,6 +8,8 @@
    绕过 Godot Editor GUI 启用步骤
 4. 自动检测 Godot 二进制，写入 ``.cli_control/godot_bin``，daemon 启动时
    会优先读取此文件
+5. 在项目根 ``.gitignore`` 追加 ``.cli_control/`` —— daemon 的机器本地状态
+   目录（godot_bin 绝对路径 / pid / port / log / 录制中间产物），不应提交
 
 完成后用户只需 ``godot-cli-control daemon start`` 即可。
 """
@@ -26,6 +28,12 @@ from .daemon import find_godot_binary, reimport_project
 PLUGIN_DIR_NAME = "godot_cli_control"
 ADDONS_DIRNAME = "addons"
 
+GITIGNORE_NAME = ".gitignore"
+# 需要 init 写进目标项目 .gitignore 的条目。用元组而非单值，给将来"增量加
+# 忽略项"留口子（与 method_blacklist_extra 同样的增量哲学）；目前只有 daemon
+# 的机器本地状态目录 .cli_control/。
+GITIGNORE_ENTRIES: tuple[str, ...] = (".cli_control/",)
+
 AUTOLOAD_KEY = "GameBridgeNode"
 AUTOLOAD_VALUE = '"*res://addons/godot_cli_control/bridge/game_bridge.gd"'
 PLUGIN_CFG_PATH = "res://addons/godot_cli_control/plugin.cfg"
@@ -43,6 +51,7 @@ def run_init(
     write_skills: bool = True,
     skills_only: bool = False,
     clobber_skills: bool = True,
+    write_gitignore: bool = True,
     *,
     output_format: str = "text",
     result: dict[str, Any] | None = None,
@@ -56,6 +65,9 @@ def run_init(
     ``clobber_skills=False``：写 skill 时遇到已存在文件就跳过（用户改过
     SKILL.md、希望保留本地版又允许 init 把缺失那条补上时用）。与
     ``write_skills=False`` / ``skills_only=True`` 都兼容。
+    ``write_gitignore=False``：跳过往项目根 ``.gitignore`` 追加 ``.cli_control/``
+    （不想让 init 碰 ``.gitignore`` 的用户逃生口）。该步骤属于"项目接入"阶段，
+    ``skills_only=True`` 时本就跳过。
 
     ``output_format='json'``：抑制全部人类可读 print；调用方（cli.cmd_init）
     传入 ``result`` 字典，本函数会回填结构化字段，由 cli 侧封 JSON envelope。
@@ -93,6 +105,7 @@ def run_init(
         project_godot_changes=[],
         godot_bin=None,
         skills_written=[],
+        gitignore_added=[],
     )
 
     if not (project_root / "project.godot").is_file():
@@ -157,6 +170,15 @@ def run_init(
                 "（跳过资源重新导入；首次 daemon start 会兜底重建 cache）"
             )
 
+        # .gitignore：无条件确保（不依赖 godot_bin 是否检测到——daemon 早晚
+        # 会建 .cli_control/，提前忽略最稳）。属于"项目接入"阶段，故在
+        # not skills_only 块内。
+        if write_gitignore:
+            added = _ensure_gitignore_entries(project_root)
+            if added:
+                _say(f"修改 .gitignore：忽略 {', '.join(added)}")
+            _record(gitignore_added=added)
+
     if write_skills:
         # lazy import：保持与 cli.cmd_init 那侧 `from .init_cmd import run_init`
         # 对称，两边都不在模块顶层 import，避免任一方将来改成顶层 import
@@ -319,3 +341,69 @@ def _ensure_in_packed_array(
         body.rstrip("\n") + "\n" + f'{key}=PackedStringArray("{value}")\n'
     )
     return text[:start] + new_body + text[end:], True
+
+
+# ── .gitignore 维护 ──
+
+
+def _gitignore_has_entry(text: str, entry: str) -> bool:
+    """``.gitignore`` 文本里是否已忽略 ``entry``。
+
+    宽松匹配：忽略前导 ``/`` 与尾随 ``/``、行首尾空白，所以 ``.cli_control``、
+    ``.cli_control/``、``/.cli_control/`` 视为同一条，不重复加。注释行（``#`` 开头）
+    不算数 —— 用户把它注释掉就是想让它失效，真条目仍要补。
+    """
+    target = entry.strip().strip("/")
+    for line in text.splitlines():
+        stripped = line.strip()
+        if not stripped or stripped.startswith("#"):
+            continue
+        if stripped.strip("/") == target:
+            return True
+    return False
+
+
+def _add_gitignore_entries(
+    text: str, entries: tuple[str, ...] | list[str]
+) -> tuple[str, list[str]]:
+    """纯函数：把缺失的 ``entries`` 追加到 ``.gitignore`` 文本末尾。
+
+    返回 ``(新文本, 实际新增的条目列表)``。已存在的条目跳过。追加前确保末尾
+    有换行，避免把新条目黏到原末行后面；空文本不留前导空行。行尾统一用
+    ``\\n``，CRLF 回写交给 IO 包装层（与 ``_patch_project_godot`` 同构）。
+    """
+    added: list[str] = []
+    out = text
+    for entry in entries:
+        if _gitignore_has_entry(out, entry):
+            continue
+        if out and not out.endswith("\n"):
+            out += "\n"
+        out += entry + "\n"
+        added.append(entry)
+    return out, added
+
+
+def _ensure_gitignore_entries(
+    project_root: Path, entries: tuple[str, ...] = GITIGNORE_ENTRIES
+) -> list[str]:
+    """确保项目根 ``.gitignore`` 忽略 ``entries``；返回实际新增的条目。
+
+    文件不存在则创建（LF）。已存在则沿用 ``_patch_project_godot`` 的 bytes+CRLF
+    思路：读 bytes、探测原文是否 CRLF、解码时折成 LF 便于匹配，仅在确有新增时
+    回写并把行尾翻回原样 —— 保 Windows 上 git diff 不被整文件行尾翻转污染。
+    """
+    path = project_root / GITIGNORE_NAME
+    if path.exists():
+        raw = path.read_bytes()
+        is_crlf = b"\r\n" in raw
+        text = raw.decode("utf-8").replace("\r\n", "\n")
+    else:
+        is_crlf = False
+        text = ""
+
+    new_text, added = _add_gitignore_entries(text, entries)
+    if added:
+        out = new_text.replace("\n", "\r\n") if is_crlf else new_text
+        path.write_bytes(out.encode("utf-8"))
+    return added

{godot_cli_control-0.2.10 → godot_cli_control-0.2.12}/python/godot_cli_control/templates/skill/SKILL.md

@@ -85,7 +85,7 @@ $ godot-cli-control --text exists /root/Main
 true
 
 $ godot-cli-control init
-{"ok": true, "result": {"project_root": "/path/to/proj", "plugin_copied": true, "plugin_overwritten": false, "project_godot_changes": ["autoload/GameBridgeNode", "editor_plugins/enabled"], "godot_bin": "/usr/bin/godot", "skills_written": [".../SKILL.md", ".../SKILL.md"], "skills_only": false, "write_skills": true}}
+{"ok": true, "result": {"project_root": "/path/to/proj", "plugin_copied": true, "plugin_overwritten": false, "project_godot_changes": ["autoload/GameBridgeNode", "editor_plugins/enabled"], "godot_bin": "/usr/bin/godot", "skills_written": [".../SKILL.md", ".../SKILL.md"], "gitignore_added": [".cli_control/"], "skills_only": false, "write_skills": true}}
 
 $ godot-cli-control run my_script.py
 {"ok": true, "result": {"exit_code": 0, "script": "my_script.py"}}
@@ -274,7 +274,7 @@ Or `{"steps": [...]}` wrapper form is also accepted. Steps run strictly serially
 The daemon can drive Godot's [Movie Maker](https://docs.godotengine.org/en/stable/tutorials/animation/creating_movies.html) (`--write-movie`) so input you script through this skill is captured to disk. Pipeline: Godot writes raw `.avi`, `daemon stop` shells out to `ffmpeg` to transcode that into `.mp4` next to the original.
 
 ```bash
-godot-cli-control daemon start --record --movie-path out.avi --headless --fps 60
+godot-cli-control daemon start --record --movie-path out.avi --fps 60
 godot-cli-control click /root/Main/StartButton
 godot-cli-control tap jump 0.3
 godot-cli-control daemon stop          # → produces out.mp4
@@ -283,6 +283,7 @@ godot-cli-control daemon stop          # → produces out.mp4
 Key constraints:
 
 - `--record` **requires** `--movie-path` (daemon refuses to start otherwise).
+- `--record` needs a **real renderer**, so it cannot run with `--headless`: Godot Movie Maker's `add_frame()` reads the viewport texture, which the headless dummy renderer leaves null → SIGSEGV on the first frame. The daemon therefore **rejects `--record --headless` with exit code 2** before launching Godot. You don't need to pass `--gui`: when `--record` is set the daemon auto-opens a window even in a non-TTY (subagent / pipe / CI) shell that would otherwise default to headless.
 - The `.mp4` is produced **only when `daemon stop` runs**; `kill -9` leaves the raw `.avi` behind.
 - `ffmpeg` must be on `PATH` for transcoding. If transcoding fails, the raw `.avi` is kept and `daemon stop` exits with code `2` (transcode log at `.cli_control/ffmpeg.log`).
 - `--fps` controls the **fixed simulation framerate** Godot runs at while recording — set it to your target video framerate.

{godot_cli_control-0.2.10 → godot_cli_control-0.2.12}/python/tests/test_cli.py

@@ -723,6 +723,7 @@ def test_cmd_init_catches_unexpected_exception_into_envelope(
         no_skills=False,
         skills_only=False,
         skills_no_clobber=False,
+        no_gitignore=False,
         output_format=OUTPUT_JSON,
     )
     rc = cmd_init(ns)
@@ -1258,6 +1259,47 @@ def test_daemon_start_text_mode_keeps_silent_success(
     assert capsys.readouterr().out == ""
 
 
+def test_daemon_start_rejects_record_with_explicit_headless(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """``daemon start --record --movie-path x --headless`` → ok:false 信封 +
+    EXIT_INFRA_ERROR(2)，且 message 点名 headless（CultivationWorld #180）。
+
+    显式 --headless 经 _resolve_headless 仍是 True，被 daemon.start 的 preflight
+    拒绝。find_godot_binary mock 成 None 确保 RED 时不会真去 spawn Godot。"""
+    import json as _json
+
+    (tmp_path / "project.godot").write_text("", encoding="utf-8")
+    monkeypatch.chdir(tmp_path)
+    monkeypatch.setattr(
+        "godot_cli_control.daemon.find_godot_binary", lambda: None
+    )
+
+    from godot_cli_control.cli import (
+        EXIT_INFRA_ERROR,
+        OUTPUT_JSON,
+        cmd_daemon_start,
+    )
+
+    ns = __import__("argparse").Namespace(
+        record=True,
+        movie_path=str(tmp_path / "demo.avi"),
+        headless=True,
+        gui=False,
+        fps=30,
+        port=0,
+        idle_timeout="0",
+        output_format=OUTPUT_JSON,
+    )
+    rc = cmd_daemon_start(ns)
+    assert rc == EXIT_INFRA_ERROR
+    payload = _json.loads(capsys.readouterr().out.strip())
+    assert payload["ok"] is False
+    assert "headless" in payload["error"]["message"]
+
+
 def test_daemon_stop_emits_json_envelope(
     monkeypatch: pytest.MonkeyPatch, capsys: pytest.CaptureFixture[str]
 ) -> None:
@@ -1796,6 +1838,30 @@ class TestDaemonHeadlessAutodetect:
         ns = type("NS", (), {"headless": True, "gui": False})()
         assert _resolve_headless(ns, force_gui_hint=True) is True
 
+    def test_record_flips_pipe_to_gui(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """--record 没显式 --headless 时强制开窗 —— Movie Maker 需真实渲染器，
+        headless dummy renderer 拿不到 viewport texture 会 SIGSEGV
+        （CultivationWorld #180，同 screenshot/#65）。非 TTY 默认 headless
+        的 subagent/pipe/CI 场景下，--record 也应自动翻成 GUI。"""
+        from godot_cli_control.cli import _resolve_headless
+
+        monkeypatch.setattr("sys.stdout.isatty", lambda: False)
+        ns = type("NS", (), {"headless": False, "gui": False, "record": True})()
+        assert _resolve_headless(ns) is False
+
+    def test_explicit_headless_wins_over_record_flip(
+        self, monkeypatch: pytest.MonkeyPatch
+    ) -> None:
+        """显式 --headless + --record 仍返回 True —— 不静默改写用户意图，
+        而是把矛盾交给 daemon.start 的 preflight 拒绝（给明确用法错）。"""
+        from godot_cli_control.cli import _resolve_headless
+
+        monkeypatch.setattr("sys.stdout.isatty", lambda: True)
+        ns = type("NS", (), {"headless": True, "gui": False, "record": True})()
+        assert _resolve_headless(ns) is True
+
 
 class TestScriptLikelyUsesScreenshot:
     def test_detects_method_call(self, tmp_path: Path) -> None:

{godot_cli_control-0.2.10 → godot_cli_control-0.2.12}/python/tests/test_daemon.py

@@ -80,6 +80,26 @@ def test_start_rejects_record_without_movie_path(tmp_path: Path) -> None:
         daemon.start(record=True, movie_path=None)
 
 
+def test_start_rejects_record_with_headless(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """record + headless 必须在 spawn 前拒绝。
+
+    Godot Movie Maker 在 headless dummy renderer 下拿不到 viewport texture，
+    add_frame() 收到 null 纹理直接 SIGSEGV（CultivationWorld #180，同 #65 截图）。
+    这是用法矛盾 —— preflight 报错，别让 Godot 段错误吓人。检查必须在 Godot
+    binary 查找/spawn 之前，所以即使 find_godot_binary 被 mock 成 None 也应先命中
+    headless 报错。"""
+    _touch_godot_project(tmp_path)
+    monkeypatch.setattr(
+        "godot_cli_control.daemon.find_godot_binary", lambda: None
+    )
+    daemon = Daemon(tmp_path)
+    movie = tmp_path / "rec.avi"
+    with pytest.raises(DaemonError, match="headless"):
+        daemon.start(record=True, movie_path=str(movie), headless=True)
+
+
 def test_start_rejects_when_godot_bin_missing(
     tmp_path: Path, monkeypatch: pytest.MonkeyPatch
 ) -> None:

{godot_cli_control-0.2.10 → godot_cli_control-0.2.12}/python/tests/test_init.py

@@ -428,6 +428,7 @@ def test_cmd_init_emits_success_envelope_in_json_mode(
         no_skills=False,
         skills_only=False,
         skills_no_clobber=False,
+        no_gitignore=False,
         output_format=OUTPUT_JSON,
     )
     rc = cmd_init(ns)
@@ -459,6 +460,7 @@ def test_cmd_init_emits_error_envelope_on_non_godot_dir(
         no_skills=False,
         skills_only=False,
         skills_no_clobber=False,
+        no_gitignore=False,
         output_format=OUTPUT_JSON,
     )
     rc = cmd_init(ns)
@@ -469,3 +471,184 @@ def test_cmd_init_emits_error_envelope_on_non_godot_dir(
     assert payload["ok"] is False
     assert payload["error"]["code"] == -1003  # CLIENT_CODE_USAGE
     assert "project.godot" in payload["error"]["message"]
+
+
+# ── .gitignore 维护（确保 .cli_control/ 不被提交）──
+
+
+def test_gitignore_adds_entry_to_empty_text() -> None:
+    """纯函数：空文本追加条目。"""
+    from godot_cli_control.init_cmd import _add_gitignore_entries
+
+    out, added = _add_gitignore_entries("", [".cli_control/"])
+    assert added == [".cli_control/"]
+    assert out == ".cli_control/\n"
+    # 不允许出现前导空行
+    assert not out.startswith("\n")
+
+
+def test_gitignore_appends_preserving_existing_entries() -> None:
+    """已有别的忽略项时只追加、不动原内容。"""
+    from godot_cli_control.init_cmd import _add_gitignore_entries
+
+    text = "*.tmp\nbuild/\n"
+    out, added = _add_gitignore_entries(text, [".cli_control/"])
+    assert added == [".cli_control/"]
+    assert "*.tmp" in out
+    assert "build/" in out
+    assert out.endswith(".cli_control/\n")
+
+
+def test_gitignore_idempotent_when_entry_present() -> None:
+    """已含完全相同条目 → 不重复加。"""
+    from godot_cli_control.init_cmd import _add_gitignore_entries
+
+    text = "build/\n.cli_control/\n"
+    out, added = _add_gitignore_entries(text, [".cli_control/"])
+    assert added == []
+    assert out == text
+
+
+@pytest.mark.parametrize(
+    "existing",
+    [".cli_control\n", "/.cli_control/\n", "/.cli_control\n", ".cli_control/  \n"],
+)
+def test_gitignore_idempotent_on_equivalent_variants(existing: str) -> None:
+    """带/不带斜杠、带前导 / 、带尾随空白都视为已忽略，不重复加。"""
+    from godot_cli_control.init_cmd import _add_gitignore_entries
+
+    out, added = _add_gitignore_entries(existing, [".cli_control/"])
+    assert added == []
+    assert out == existing
+
+
+def test_gitignore_commented_line_does_not_count_as_present() -> None:
+    """被注释掉的同名行不算忽略，真条目仍要补上。"""
+    from godot_cli_control.init_cmd import _add_gitignore_entries
+
+    text = "# .cli_control/\n"
+    out, added = _add_gitignore_entries(text, [".cli_control/"])
+    assert added == [".cli_control/"]
+    assert "# .cli_control/" in out  # 注释保留
+    assert out.endswith(".cli_control/\n")
+
+
+def test_gitignore_appends_newline_when_file_lacks_trailing_one() -> None:
+    """原文件末行无换行符时，新条目必须独立成行、不黏在末行后面。"""
+    from godot_cli_control.init_cmd import _add_gitignore_entries
+
+    out, added = _add_gitignore_entries("build/", [".cli_control/"])
+    assert added == [".cli_control/"]
+    assert out == "build/\n.cli_control/\n"
+
+
+def test_ensure_gitignore_creates_file_when_missing(tmp_path: Path) -> None:
+    """项目根没有 .gitignore → 创建并写入 .cli_control/。"""
+    from godot_cli_control.init_cmd import _ensure_gitignore_entries
+
+    added = _ensure_gitignore_entries(tmp_path)
+    gi = tmp_path / ".gitignore"
+    assert gi.is_file()
+    assert ".cli_control/" in gi.read_text(encoding="utf-8")
+    assert added == [".cli_control/"]
+
+
+def test_ensure_gitignore_idempotent_across_runs(tmp_path: Path) -> None:
+    """连跑两次只写一条，不重复。"""
+    from godot_cli_control.init_cmd import _ensure_gitignore_entries
+
+    _ensure_gitignore_entries(tmp_path)
+    added2 = _ensure_gitignore_entries(tmp_path)
+    assert added2 == []
+    content = (tmp_path / ".gitignore").read_text(encoding="utf-8")
+    assert content.count(".cli_control/") == 1
+
+
+def test_ensure_gitignore_preserves_crlf(tmp_path: Path) -> None:
+    """已有 CRLF 的 .gitignore 在追加后必须仍是 CRLF，不混入裸 LF。"""
+    from godot_cli_control.init_cmd import _ensure_gitignore_entries
+
+    gi = tmp_path / ".gitignore"
+    gi.write_bytes(b"*.tmp\r\nbuild/\r\n")
+    _ensure_gitignore_entries(tmp_path)
+    after = gi.read_bytes()
+    assert b".cli_control/\r\n" in after
+    bare_lf = after.count(b"\n") - after.count(b"\r\n")
+    assert bare_lf == 0, f"出现裸 LF：{bare_lf} 处"
+
+
+def test_run_init_adds_cli_control_to_gitignore(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """端到端：run_init 默认在项目根 .gitignore 忽略 .cli_control/。"""
+    monkeypatch.delenv("GODOT_BIN", raising=False)
+    monkeypatch.setattr(
+        "godot_cli_control.init_cmd.find_godot_binary", lambda: None
+    )
+    proj = _minimal_project(tmp_path)
+    assert run_init(proj) == 0
+    gi = (proj / ".gitignore").read_text(encoding="utf-8")
+    assert ".cli_control/" in gi
+
+
+def test_run_init_no_gitignore_skips_gitignore(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """write_gitignore=False → 不创建 / 不改 .gitignore。"""
+    monkeypatch.delenv("GODOT_BIN", raising=False)
+    monkeypatch.setattr(
+        "godot_cli_control.init_cmd.find_godot_binary", lambda: None
+    )
+    proj = _minimal_project(tmp_path)
+    assert run_init(proj, write_gitignore=False) == 0
+    assert not (proj / ".gitignore").exists()
+
+
+def test_run_init_skills_only_skips_gitignore(tmp_path: Path) -> None:
+    """skills_only 属于纯刷 SKILL.md，不应碰 .gitignore。"""
+    proj = _make_min_godot_project(tmp_path)
+    assert run_init(proj, skills_only=True) == 0
+    assert not (proj / ".gitignore").exists()
+
+
+def test_run_init_json_records_gitignore_added(
+    tmp_path: Path, monkeypatch: pytest.MonkeyPatch
+) -> None:
+    """json 模式 result 必须回填 gitignore_added 字段。"""
+    monkeypatch.delenv("GODOT_BIN", raising=False)
+    monkeypatch.setattr(
+        "godot_cli_control.init_cmd.find_godot_binary", lambda: None
+    )
+    proj = _make_min_godot_project(tmp_path)
+    result: dict[str, object] = {}
+    assert run_init(proj, output_format="json", result=result) == 0
+    assert result["gitignore_added"] == [".cli_control/"]
+
+
+def test_cmd_init_no_gitignore_flag_skips(
+    tmp_path: Path,
+    monkeypatch: pytest.MonkeyPatch,
+    capsys: pytest.CaptureFixture[str],
+) -> None:
+    """CLI 层：--no-gitignore（ns.no_gitignore=True）不写 .gitignore。"""
+    import argparse
+
+    from godot_cli_control.cli import OUTPUT_JSON, cmd_init
+
+    monkeypatch.delenv("GODOT_BIN", raising=False)
+    monkeypatch.setattr(
+        "godot_cli_control.init_cmd.find_godot_binary", lambda: None
+    )
+    proj = _make_min_godot_project(tmp_path)
+    ns = argparse.Namespace(
+        path=str(proj),
+        force=False,
+        no_skills=False,
+        skills_only=False,
+        skills_no_clobber=False,
+        no_gitignore=True,
+        output_format=OUTPUT_JSON,
+    )
+    assert cmd_init(ns) == 0
+    capsys.readouterr()
+    assert not (proj / ".gitignore").exists()