snapstep 0.2.0__py3-none-any.whl

snapstep/__init__.py

@@ -0,0 +1,3 @@
+"""SnapStep — 录屏自动生成图文教程。"""
+
+__version__ = "0.2.0"

snapstep/__main__.py

@@ -0,0 +1,6 @@
+"""python -m snapstep 入口。"""
+
+from .cli import main
+
+if __name__ == "__main__":
+    main()

snapstep/capture.py

@@ -0,0 +1,161 @@
+"""屏幕截图与步骤标注。
+
+导入本模块只需 Pillow；mss 延迟到真正截屏时才加载，
+保证导出器/测试在没有屏幕的环境里也能工作。
+"""
+
+from __future__ import annotations
+
+import time
+from pathlib import Path
+
+from PIL import Image, ImageDraw, ImageFont
+
+# 点击高亮圈颜色（快照红）
+ACCENT = (245, 63, 63)
+
+
+class ScreenCapture:
+    """基于 mss 的截屏器。线程注意：mss 实例不跨线程，按线程懒加载。"""
+
+    def __init__(self) -> None:
+        self._sct = None
+
+    def _client(self):
+        if self._sct is None:
+            import mss
+
+            self._sct = mss.mss()
+        return self._sct
+
+    def monitor_for_point(self, x: int, y: int) -> dict:
+        """返回包含该点显示器的 mss monitor 字典；找不到时退回主显示器。"""
+        monitors = self._client().monitors
+        for mon in monitors[1:]:
+            if (
+                mon["left"] <= x < mon["left"] + mon["width"]
+                and mon["top"] <= y < mon["top"] + mon["height"]
+            ):
+                return dict(mon)
+        return dict(monitors[1] if len(monitors) > 1 else monitors[0])
+
+    def capture_point(self, x: int, y: int) -> tuple[Image.Image, dict]:
+        """截取包含 (x, y) 的显示器，返回 (PIL 图像, monitor 字典)。"""
+        mon = self.monitor_for_point(x, y)
+        shot = self._client().grab(mon)
+        img = Image.frombytes("RGB", shot.size, shot.bgra, "raw", "BGRX")
+        return img, mon
+
+
+def save_screenshot(
+    img: Image.Image,
+    session_dir: Path,
+    index: int,
+    image_format: str = "png",
+    suffix: str = "",
+) -> str:
+    """保存原始截图，返回相对 session 目录的 POSIX 风格路径。
+
+    suffix 用于区分同一步骤的候选帧（如 "-imm" / "-set"）。
+    """
+    images_dir = session_dir / "images"
+    images_dir.mkdir(parents=True, exist_ok=True)
+    path = images_dir / f"step-{index:02d}{suffix}.{image_format}"
+    img.save(path)
+    return path.relative_to(session_dir).as_posix()
+
+
+# 图片相似度：缩到 96x54 灰度后逐像素求平均绝对差（0~255）。
+# < 2.0 视为「画面没变」，> 4.0 视为「明显变化」。
+_SIMILARITY_SIZE = (96, 54)
+
+
+def mean_diff(a: Path | Image.Image, b: Path | Image.Image) -> float:
+    """两张截图的平均像素差（0~255），越小越相似。"""
+    pa = a if isinstance(a, Image.Image) else Image.open(a)
+    pb = b if isinstance(b, Image.Image) else Image.open(b)
+    ga = pa.convert("L").resize(_SIMILARITY_SIZE)
+    gb = pb.convert("L").resize(_SIMILARITY_SIZE)
+    da = list(ga.getdata())
+    db = list(gb.getdata())
+    total = sum(abs(x - y) for x, y in zip(da, db, strict=True))
+    return total / len(da)
+
+
+def settle_grab(
+    capture: ScreenCapture,
+    monitor: dict,
+    max_wait_ms: int,
+    poll_ms: int = 150,
+    stable_diff: float = 1.5,
+) -> tuple[Image.Image, int]:
+    """轮询截屏直到画面连续两帧几乎不变（界面稳定），或超时。
+
+    返回 (稳定帧图像, 实际等待毫秒数)。
+    """
+    deadline = time.monotonic() + max(max_wait_ms, 0) / 1000
+    last = capture.grab_monitor(monitor)
+    waited = 0
+    while True:
+        if time.monotonic() >= deadline:
+            return last, waited
+        time.sleep(poll_ms / 1000)
+        waited += poll_ms
+        current = capture.grab_monitor(monitor)
+        if mean_diff(last, current) < stable_diff:
+            return current, waited
+        last = current
+
+
+def _load_font(size: int) -> ImageFont.FreeTypeFont | ImageFont.ImageFont:
+    for name in ("msyh.ttc", "arial.ttf"):  # 优先微软雅黑，回退 Arial
+        try:
+            return ImageFont.truetype(name, size)
+        except OSError:
+            continue
+    return ImageFont.load_default()
+
+
+def annotate(
+    img: Image.Image, rel_x: float, rel_y: float, number: int, radius: int = 28
+) -> Image.Image:
+    """在截图上标注点击位置：红色高亮圈 + 序号徽章，返回新图。"""
+    out = img.convert("RGBA")
+    overlay = Image.new("RGBA", out.size, (0, 0, 0, 0))
+    d = ImageDraw.Draw(overlay)
+
+    cx, cy = rel_x * out.width, rel_y * out.height
+    ring_w = max(3, out.width // 450)
+    # 外圈柔光 + 内圈实线
+    d.ellipse(
+        [cx - radius - 8, cy - radius - 8, cx + radius + 8, cy + radius + 8],
+        outline=ACCENT + (80,),
+        width=ring_w + 3,
+    )
+    d.ellipse(
+        [cx - radius, cy - radius, cx + radius, cy + radius],
+        outline=ACCENT + (255,),
+        width=ring_w,
+    )
+
+    # 序号徽章放在圈右上，越界时往里收
+    badge_r = max(14, int(radius * 0.62))
+    bx = min(max(cx + radius + 6, badge_r), out.width - badge_r - 2)
+    by = max(min(cy - radius - 6, out.height - badge_r - 2), badge_r + 2)
+    d.ellipse(
+        [bx - badge_r, by - badge_r, bx + badge_r, by + badge_r],
+        fill=ACCENT + (235,),
+    )
+    out = Image.alpha_composite(out, overlay)
+
+    dd = ImageDraw.Draw(out)
+    text = str(number)
+    font = _load_font(badge_r * 2 - 4)
+    left, top, right, bottom = dd.textbbox((0, 0), text, font=font)
+    dd.text(
+        (bx - (right - left) / 2 - left, by - (bottom - top) / 2 - top),
+        text,
+        font=font,
+        fill=(255, 255, 255, 255),
+    )
+    return out.convert("RGB")

snapstep/cli.py

@@ -0,0 +1,298 @@
+"""命令行入口。
+
+    snapstep            启动托盘 GUI（默认）
+    snapstep record     命令行录制，回车结束
+    snapstep export     导出已有会话
+    snapstep config     查看/修改配置
+    snapstep demo       生成一份示例教程（无需录制，验证安装）
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+from dataclasses import fields as dc_fields
+from pathlib import Path
+
+from . import __version__
+from .config import Config, load_config, save_config
+from .models import Session
+from .writer import AIWriter, TemplateWriter, apply_copy
+
+
+def generate_and_export(
+    session: Session,
+    session_dir: Path,
+    cfg: Config,
+    fmt: str | None = None,
+    use_ai: bool | None = None,
+) -> tuple[str, list[Path]]:
+    """生成文案并导出。CLI 与 GUI 共用。返回 (writer 名称, 导出文件列表)。"""
+    from .export import export_session
+
+    use_ai = cfg.ai_enabled() if use_ai is None else (use_ai and cfg.ai_enabled())
+    ai = (
+        AIWriter(cfg.api.base_url, cfg.api.api_key, cfg.api.model, cfg.api.language)
+        if use_ai
+        else None
+    )
+    used = apply_copy(session, TemplateWriter(cfg.api.language), ai)
+    session.save(session_dir)
+    paths = export_session(
+        session, session_dir, fmt or cfg.export.format, None, cfg.export.embed_images
+    )
+    return used, paths
+
+
+# ---------- 子命令 ----------
+
+
+def cmd_record(args, cfg: Config) -> int:
+    from .recorder import Recorder
+
+    privacy = "开启" if cfg.privacy.privacy_mode else "关闭"
+    ai = "已配置" if cfg.ai_enabled() else "未配置（使用本地模板）"
+    print(f"SnapStep v{__version__} 开始录制")
+    print(f"  隐私模式：{privacy}（截屏{'被跳过' if cfg.privacy.privacy_mode else '正常'}）")
+    print(f"  AI 文案：{ai}")
+    print("  进行你的操作，回到本窗口按回车结束录制。\n")
+
+    recorder = Recorder(cfg, out_dir=Path(args.out) if args.out else None)
+    recorder.on_step_captured = lambda step: print(
+        f"  [步骤 {step.index}] {step.window_title or '未知窗口'}"
+    )
+    recorder.start()
+    try:
+        input()
+    except KeyboardInterrupt:
+        pass
+    session, session_dir = recorder.stop_and_save()
+    print(f"\n录制完成：{len(session.steps)} 个步骤 → {session_dir}")
+
+    used, paths = generate_and_export(
+        session, session_dir, cfg, fmt=args.format, use_ai=not args.no_ai
+    )
+    _print_export_result(used, paths)
+    return 0
+
+
+def cmd_export(args, cfg: Config) -> int:
+    session_dir = Path(args.session_dir)
+    if not (session_dir / "session.json").exists():
+        print(f"错误：{session_dir} 下没有 session.json", file=sys.stderr)
+        return 1
+    session = Session.load(session_dir)
+    used, paths = generate_and_export(
+        session, session_dir, cfg, fmt=args.format, use_ai=not args.no_ai
+    )
+    _print_export_result(used, paths)
+    return 0
+
+
+def _print_export_result(used: str, paths: list[Path]) -> None:
+    if used == "ai":
+        print("文案：AI 生成")
+    else:
+        print("文案：本地模板（AI 未配置或调用失败，已自动兜底）")
+    for path in paths:
+        print(f"已导出：{path}")
+
+
+def cmd_config(args, cfg: Config) -> int:
+    if args.config_action == "list" or args.key is None:
+        print(json.dumps(_config_to_dict(cfg), ensure_ascii=False, indent=2))
+        return 0
+    if args.config_action == "get":
+        print(_get_key(cfg, args.key))
+        return 0
+    # set
+    _set_key(cfg, args.key, args.value)
+    save_config(cfg)
+    print(f"已保存 {args.key} = {args.value}")
+    return 0
+
+
+def _config_to_dict(cfg: Config) -> dict:
+    return {
+        "hotkey": cfg.hotkey,
+        "capture": {f.name: getattr(cfg.capture, f.name) for f in dc_fields(cfg.capture)},
+        "privacy": {f.name: getattr(cfg.privacy, f.name) for f in dc_fields(cfg.privacy)},
+        "api": {f.name: getattr(cfg.api, f.name) for f in dc_fields(cfg.api)},
+        "export": {f.name: getattr(cfg.export, f.name) for f in dc_fields(cfg.export)},
+    }
+
+
+def _get_key(cfg: Config, key: str) -> object:
+    target: object = cfg
+    for part in key.split("."):
+        target = getattr(target, part)
+    return target
+
+
+def _set_key(cfg: Config, key: str, value: str) -> None:
+    parts = key.split(".")
+    target: object = cfg
+    for part in parts[:-1]:
+        target = getattr(target, part)
+    leaf = parts[-1]
+    if not hasattr(target, leaf):
+        valid = _valid_keys(cfg)
+        raise SystemExit(f"未知配置项 {key}。可用项：\n  " + "\n  ".join(valid))
+    current = getattr(target, leaf)
+    if isinstance(current, bool):
+        setattr(target, leaf, value.lower() in ("1", "true", "yes", "on"))
+    elif isinstance(current, int):
+        setattr(target, leaf, int(value))
+    else:
+        setattr(target, leaf, value)
+
+
+def _valid_keys(cfg: Config) -> list[str]:
+    keys = ["hotkey"]
+    for section in ("capture", "privacy", "api", "export"):
+        obj = getattr(cfg, section)
+        keys += [f"{section}.{f.name}" for f in dc_fields(obj)]
+    return keys
+
+
+def cmd_demo(args, cfg: Config) -> int:
+    session = _build_demo_session()
+    session_dir = Path(args.out)
+    _render_demo_screenshots(session, session_dir)
+    used, paths = generate_and_export(
+        session, session_dir, cfg, fmt=args.format, use_ai=not args.no_ai
+    )
+    print(f"示例会话已生成：{session_dir}")
+    _print_export_result(used, paths)
+    return 0
+
+
+def _build_demo_session() -> Session:
+    from .models import Step, TypedRun
+
+    session = Session(title=None, intro=None)
+    demo_steps = [
+        ("发布新文章 - 后台管理", (0.5, 0.12), [("操作手册", False)]),
+        ("发布新文章 - 后台管理", (0.32, 0.45), []),
+        ("确认发布 - 后台管理", (0.5, 0.62), [("文章已就绪，点击确认", False)]),
+    ]
+    for i, (win, (rx, ry), runs) in enumerate(demo_steps, 1):
+        step = Step(
+            index=i,
+            created_at=f"2026-01-01T10:0{i}:00",
+            window_title=win,
+            click_x=int(rx * 1920),
+            click_y=int(ry * 1080),
+            monitor_width=1920,
+            monitor_height=1080,
+            typed_runs=[TypedRun(text=t, is_secret=s) for t, s in runs],
+        )
+        session.steps.append(step)
+    return session
+
+
+def _render_demo_screenshots(session: Session, session_dir: Path) -> None:
+    """用 Pillow 画出假窗口截图，让 demo 无需真实录屏。"""
+    from PIL import Image, ImageDraw, ImageFont
+
+    from .capture import save_screenshot
+
+    def font(size: int):
+        for name in ("msyh.ttc", "arial.ttf"):
+            try:
+                return ImageFont.truetype(name, size)
+            except OSError:
+                continue
+        return ImageFont.load_default()
+
+    for step in session.steps:
+        img = Image.new("RGB", (1280, 800), (247, 248, 250))
+        d = ImageDraw.Draw(img)
+        # 假窗口
+        win = [120, 90, 1160, 700]
+        d.rounded_rectangle(win, 12, fill=(255, 255, 255), outline=(229, 230, 235), width=2)
+        d.rounded_rectangle([win[0], win[1], win[2], win[1] + 44], 12, fill=(242, 243, 245))
+        d.rectangle([win[0], win[1] + 30, win[2], win[1] + 44], fill=(242, 243, 245))
+        for k, color in enumerate([(255, 95, 86), (255, 189, 46), (39, 201, 63)]):
+            x0, x1 = win[0] + 18 + k * 26, win[0] + 32 + k * 26
+            d.ellipse([x0, win[1] + 15, x1, win[1] + 29], fill=color)
+        d.text(
+            (win[0] + 110, win[1] + 10),
+            step.window_title or "示例窗口",
+            font=font(17),
+            fill=(31, 35, 41),
+        )
+        # 几行假正文
+        for k in range(4):
+            y = win[1] + 80 + k * 46
+            x1 = win[2] - 40 - k * 130
+            d.rounded_rectangle([win[0] + 40, y, x1, y + 22], 6, fill=(240, 241, 244))
+        # 点击处的假按钮
+        cx = win[0] + step.rel_x * (win[2] - win[0])
+        cy = win[1] + step.rel_y * (win[3] - win[1])
+        d.rounded_rectangle([cx - 80, cy - 22, cx + 80, cy + 22], 8, fill=(245, 63, 63))
+        d.text((cx - 32, cy - 11), "确 定", font=font(16), fill=(255, 255, 255))
+        step.screenshot = save_screenshot(img, session_dir, step.index)
+
+
+# ---------- 入口 ----------
+
+
+def main(argv: list[str] | None = None) -> int:
+    for stream in (sys.stdout, sys.stderr):
+        try:
+            stream.reconfigure(encoding="utf-8")
+        except Exception:
+            pass
+
+    parser = argparse.ArgumentParser(
+        prog="snapstep",
+        description="录屏自动生成图文教程 / Record your screen, get a step-by-step guide.",
+    )
+    parser.add_argument("--version", action="version", version=f"SnapStep {__version__}")
+    sub = parser.add_subparsers(dest="command")
+
+    p_record = sub.add_parser("record", help="开始录制，回车结束")
+    p_record.add_argument("--out", help="会话输出目录（默认 ~/.snapstep/sessions/<时间戳>）")
+    p_record.add_argument("--format", choices=["md", "html", "docx", "all"], help="导出格式")
+    p_record.add_argument("--no-ai", action="store_true", help="跳过 AI 文案，直接用本地模板")
+
+    p_export = sub.add_parser("export", help="导出已有会话")
+    p_export.add_argument("session_dir", help="会话目录（含 session.json）")
+    p_export.add_argument("--format", choices=["md", "html", "docx", "all"])
+    p_export.add_argument("--out", help="导出目录（默认 <会话>/export）")
+    p_export.add_argument("--no-ai", action="store_true")
+
+    p_config = sub.add_parser("config", help="查看/修改配置")
+    p_config.add_argument(
+        "config_action", nargs="?", choices=["list", "get", "set"], default="list"
+    )
+    p_config.add_argument("key", nargs="?", help="如 api.api_key、privacy.privacy_mode、hotkey")
+    p_config.add_argument("value", nargs="?", help="set 时的新值")
+
+    p_demo = sub.add_parser("demo", help="生成示例教程，验证安装")
+    p_demo.add_argument("--out", default="snapstep-demo")
+    p_demo.add_argument("--format", choices=["md", "html", "docx", "all"])
+    p_demo.add_argument("--no-ai", action="store_true")
+
+    args = parser.parse_args(argv)
+    cfg = load_config()
+
+    if args.command == "record":
+        return cmd_record(args, cfg)
+    if args.command == "export":
+        return cmd_export(args, cfg)
+    if args.command == "config":
+        return cmd_config(args, cfg)
+    if args.command == "demo":
+        return cmd_demo(args, cfg)
+
+    from .ui.tray import run_gui
+
+    run_gui()
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

snapstep/config.py

@@ -0,0 +1,109 @@
+"""SnapStep 配置：JSON 持久化在 ~/.snapstep/config.json。"""
+
+from __future__ import annotations
+
+import json
+from dataclasses import asdict, dataclass, field
+from pathlib import Path
+
+# 设置界面里的 API 预设（OpenAI 兼容端点）
+API_PRESETS: dict[str, dict[str, str]] = {
+    "GLM 智谱": {
+        "base_url": "https://open.bigmodel.cn/api/paas/v4",
+        "model": "glm-4-flash",
+    },
+    "DeepSeek": {
+        "base_url": "https://api.deepseek.com/v1",
+        "model": "deepseek-chat",
+    },
+    "OpenAI": {
+        "base_url": "https://api.openai.com/v1",
+        "model": "gpt-4o-mini",
+    },
+    "自定义": {"base_url": "", "model": ""},
+}
+
+
+@dataclass
+class CaptureConfig:
+    settle_max_ms: int = 1500  # 点击后等待界面稳定的上限，期间持续比对帧，稳定即取「稳定帧」
+    image_format: str = "png"
+    filter_idle_clicks: bool = True  # 停止时自动剔除画面无变化且无输入的无效点击
+
+
+@dataclass
+class PrivacyConfig:
+    privacy_mode: bool = False  # 开启后完全不截屏，只记录步骤
+    mask_passwords: bool = True  # 密码框键入不记录明文（尽力检测）
+
+
+@dataclass
+class ApiConfig:
+    base_url: str = ""  # 为空时不调用 AI，走本地模板文案
+    api_key: str = ""
+    model: str = ""
+    language: str = "zh"  # AI 文案语言：zh / en
+
+
+@dataclass
+class ExportConfig:
+    format: str = "html"  # md / html / docx
+    embed_images: bool = True  # HTML 单文件内嵌 base64，方便直接分享
+
+
+@dataclass
+class Config:
+    hotkey: str = "<ctrl>+<alt>+s"  # 开始/停止录制（GUI 生效）
+    capture: CaptureConfig = field(default_factory=CaptureConfig)
+    privacy: PrivacyConfig = field(default_factory=PrivacyConfig)
+    api: ApiConfig = field(default_factory=ApiConfig)
+    export: ExportConfig = field(default_factory=ExportConfig)
+
+    def ai_enabled(self) -> bool:
+        return bool(self.api.base_url and self.api.api_key and self.api.model)
+
+
+def config_dir() -> Path:
+    return Path.home() / ".snapstep"
+
+
+def sessions_dir() -> Path:
+    return config_dir() / "sessions"
+
+
+def config_path() -> Path:
+    return config_dir() / "config.json"
+
+
+def load_config() -> Config:
+    """加载配置；文件缺失或字段不完整时按默认值补齐。"""
+    path = config_path()
+    cfg = Config()
+    if not path.exists():
+        return cfg
+    try:
+        data = json.loads(path.read_text(encoding="utf-8"))
+    except (json.JSONDecodeError, OSError):
+        return cfg
+    cfg.hotkey = data.get("hotkey", cfg.hotkey)
+    for section, cls in (
+        ("capture", CaptureConfig),
+        ("privacy", PrivacyConfig),
+        ("api", ApiConfig),
+        ("export", ExportConfig),
+    ):
+        raw = data.get(section, {})
+        current = getattr(cfg, section)
+        for f in cls.__dataclass_fields__:
+            if f in raw:
+                setattr(current, f, raw[f])
+    return cfg
+
+
+def save_config(cfg: Config) -> Path:
+    path = config_path()
+    path.parent.mkdir(parents=True, exist_ok=True)
+    path.write_text(
+        json.dumps(asdict(cfg), ensure_ascii=False, indent=2), encoding="utf-8"
+    )
+    return path

snapstep/export/__init__.py

@@ -0,0 +1,68 @@
+"""导出器包：Markdown / HTML / Word + 标注图准备。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from PIL import Image
+
+from ..models import Session
+
+FORMATS = ("md", "html", "docx")
+
+
+def prepare_images(
+    session: Session, session_dir: Path, out_dir: Path
+) -> dict[int, Path]:
+    """为每一步生成带点击高亮和序号徽章的标注图。
+
+    返回 {step.index: 标注图路径}；没有截图或原始文件缺失的步骤跳过。
+    """
+    from ..capture import annotate
+
+    images_dir = out_dir / "images"
+    images_dir.mkdir(parents=True, exist_ok=True)
+    mapping: dict[int, Path] = {}
+    for step in session.steps:
+        if not step.screenshot:
+            continue
+        raw = session_dir / step.screenshot
+        if not raw.exists():
+            continue
+        img = Image.open(raw)
+        annotated = annotate(img, step.rel_x, step.rel_y, step.index)
+        path = images_dir / f"step-{step.index:02d}.png"
+        annotated.save(path)
+        mapping[step.index] = path
+    return mapping
+
+
+def export_session(
+    session: Session,
+    session_dir: Path,
+    fmt: str,
+    out_dir: Path | None = None,
+    embed_images: bool = True,
+) -> list[Path]:
+    """把 Session 导出为指定格式（fmt=all 时导出全部三种）。"""
+    from .docx_export import export_docx
+    from .html_export import export_html
+    from .markdown_export import export_markdown
+
+    out_dir = out_dir or session_dir / "export"
+    out_dir.mkdir(parents=True, exist_ok=True)
+    fmts = list(FORMATS) if fmt == "all" else [fmt]
+    unknown = set(fmts) - set(FORMATS)
+    if unknown:
+        raise ValueError(f"未知导出格式：{'、'.join(sorted(unknown))}（支持 {FORMATS}）")
+
+    images = prepare_images(session, session_dir, out_dir)
+    results: list[Path] = []
+    for f in fmts:
+        if f == "md":
+            results.append(export_markdown(session, images, out_dir))
+        elif f == "html":
+            results.append(export_html(session, images, out_dir, embed_images))
+        elif f == "docx":
+            results.append(export_docx(session, images, out_dir))
+    return results

snapstep/export/docx_export.py

@@ -0,0 +1,38 @@
+"""Word（docx）导出。"""
+
+from __future__ import annotations
+
+from pathlib import Path
+
+from docx import Document
+from docx.shared import Inches
+
+from ..models import Session
+
+
+def export_docx(
+    session: Session, images: dict[int, Path], out_dir: Path
+) -> Path:
+    doc = Document()
+    doc.add_heading(session.title or "操作教程", level=0)
+    if session.intro:
+        doc.add_paragraph(session.intro)
+
+    for step in session.steps:
+        doc.add_heading(f"{step.index}. {step.title or f'步骤 {step.index}'}", level=2)
+        if step.description:
+            doc.add_paragraph(step.description)
+        typed = step.typed_text()
+        if typed:
+            p = doc.add_paragraph()
+            run = p.add_run(f"输入：{typed}")
+            run.italic = True
+        if step.has_secret():
+            doc.add_paragraph("（本步包含密码输入，内容已隐藏）")
+        img = images.get(step.index)
+        if img:
+            doc.add_picture(str(img), width=Inches(5.9))
+
+    path = out_dir / "guide.docx"
+    doc.save(path)
+    return path