travel-guidebook-engine

travel-guidebook-engine 是旅行路书引擎的 npm CLI。它把引擎需要的 Claude skills、配置模板、HTML 转 PDF 工具和小红书服务 compose 示例安装到一个目标旅行项目里，让目标项目可以生成、检查、继续处理旅行路书。

安装

要求 Node.js >=20.17.0。

推荐直接用 npx 安装到目标项目：

npx -y travel-guidebook-engine install <target>

也可以先全局安装：

npm install -g travel-guidebook-engine
travel-engine
travel-engine install <target>

仓库里的 install.sh 仍保留为本地兼容安装脚本；新项目优先使用 npm CLI。

交互菜单

在本地终端里直接运行：

travel-engine

CLI 会打开主菜单，提供安装/更新、继续安装、检查项目、小红书服务状态/启动/登录、配置引导和命令帮助。这个入口适合第一次配置或不想记命令时使用。

脚本、CI 或自动化环境应继续使用显式命令，例如 travel-engine install <target> --yes --xhs npm。无 TTY 的空命令只会打印 Usage，不会弹出交互菜单。

常用命令

# 安装或更新目标旅行项目
travel-engine install <target>

# 从上次中断的安装状态继续
travel-engine resume <target>

# 检查目标项目是否具备运行条件
travel-engine doctor <target>

# 代理调用目标项目里的 travel-planner/scripts/xhs.sh
travel-engine xhs <target> status
travel-engine xhs <target> start
travel-engine xhs <target> stop
travel-engine xhs <target> login
travel-engine xhs <target> search --raw "目的地 关键词"

xhs 命令只是转发到目标项目的 .claude/skills/travel-planner/scripts/xhs.sh，所以小红书搜索、登录和启动行为以该脚本为准。

安装选项

travel-engine install <target> --yes --xhs npm
travel-engine install <target> --dry-run
travel-engine install <target> --skip-deps
travel-engine install <target> --no-xhs
travel-engine install <target> --xhs docker
travel-engine install <target> --xhs existing --xhs-url http://127.0.0.1:18060
travel-engine install <target> --xhs skip

• --yes：非交互安装，使用默认选择。
• --dry-run：仅验证 CLI 参数并返回 dry-run 结果，不写文件、不执行安装步骤。
• --skip-deps：只复制文件和写配置，不执行依赖安装。
• --no-xhs：在 --yes 模式下等同 --xhs skip；交互模式仍会询问小红书方式，以问答选择为准。
• --xhs npm|docker|existing|skip：用于安装向导里的小红书方式选择 / 跳过选择，当前不会自动写入小红书后端配置或连接服务。

这些选项当前不会通过 answers.xhs 或 flags.xhsUrl 写入目标项目配置，也不会改变目标项目的小红书后端运行方式。真正的小红书后端由目标项目里的 .claude/skills/travel-planner/scripts/xhs.sh 按自身 detect / env / compose 逻辑处理。--xhs existing --xhs-url <url> 当前仅被 CLI 解析保留，不会自动写入服务配置；如果需要使用已有服务，请在目标项目脚本或环境变量里配置。

npm CLI 会把 cloakbrowser 和 playwright-core 合并进目标项目 dependencies，并可执行 npm install 和 npx cloakbrowser install。这是当前推荐的“大一统”安装方式，不依赖目标机器预装 Chrome、Edge 或 Chromium。

写入内容

安装器会按选择写入或更新这些内容：

• .claude/skills/：旅行路书、调研、规划和小红书脚本相关 skills。
• html2pdf.mjs：HTML 转 PDF 工具。
• config/：示例配置模板。
• xiaohongshu/docker-compose.example.yml：小红书服务 compose 示例，镜像为 muuua/travel-hongshu:latest。
• package.json：合并 cloakbrowser / playwright-core 依赖。
• .gitignore：补充本地密钥、状态和打包产物忽略项。
• .travel-engine/install-state.json：安装进度状态。
• .mcp.json：高德 MCP 配置。
• .claude/settings.local.json：Claude 本地环境变量配置。
• ~/.flyai/config.json：flyai key 配置。

安全和恢复

• --dry-run 仅返回 dry-run 结果，不写文件、不执行安装步骤。
• 安装状态保存在 .travel-engine/install-state.json，可用 travel-engine resume <target> 继续。
• 已有真实配置不会被覆盖；只有不存在或仍含占位值的配置文件会被写入。
• 修改 package.json 和 .gitignore 前会生成备份。
• 配置、状态、package.json、.gitignore 和 xhs.sh 执行路径会拒绝符号链接写入 / 执行；引擎资源复制会安全替换目标符号链接，不会跟随写到目标目录外。
• 密钥不会写入安装状态文件。

小红书服务

安装时可以预选或跳过小红书相关处理：

• --xhs npm：在安装向导中预选 npm/binary 路线；当前不自动写后端配置。
• --xhs docker：在安装向导中预选 Docker 路线；当前不自动写后端配置。
• --xhs existing --xhs-url <url>：CLI 会解析并保留该参数，但当前不会自动写入服务配置或连接已有服务。
• --xhs skip：在安装向导中预选跳过小红书。
• --no-xhs：只在 --yes 模式下等同 --xhs skip；交互模式仍会询问小红书方式。

travel-engine xhs <target> ... 运行时仍只代理调用目标项目里的 .claude/skills/travel-planner/scripts/xhs.sh；后端 detect、环境变量和 compose 行为都以该脚本为准。如需使用已有服务，请在目标项目脚本或环境里配置。

Docker compose 示例在 xiaohongshu/docker-compose.example.yml，默认镜像是 muuua/travel-hongshu:latest。源码仓库是 cappuxcz/travel-hongshu，更多细节见 xiaohongshu/README.md。

发布

正式发布通过 Gitea Actions 处理。推送 tag vX.Y.Z 后 workflow 会：

• 校验 tag 版本和 package.json 版本一致。
• 运行测试和 npm pack --dry-run --json。
• 发布 npm 包 travel-guidebook-engine。
• 创建 Gitea Release 并上传 npm tarball。
• 构建并推送 Docker Hub 多架构镜像：
  • muuua/travels:${PACKAGE_VERSION}
  • muuua/travels:latest

仓库需要配置这些 secrets / 变量：

• NPM_TOKEN
• GITEA_TOKEN
• DOCKERHUB_USERNAME：填 muuua
• DOCKERHUB_TOKEN

发布服务端说明见 publish/README.md。

本地验证

npm test
npm pack --dry-run --json
npm run test:workflow

更多文档

• docs/ARCHITECTURE.md：引擎结构说明。
• xiaohongshu/README.md：小红书服务说明。
• publish/README.md：路书发布服务说明。
• examples/2026-06-威海-2对情侣-4天3晚/：已脱敏示例，可作为产物参考，不是安装主流程。