self-drive-planner

一个面向中国境内自驾旅行的 Codex / Claude Code Skill。它把出发地、天数、驾驶上限和吃玩偏好整理成可执行的逐日路线，并生成可交互的地图路书。

核心原则是：驾驶安全优先、少折返、跨城日不塞景点、社区内容只作体验线索、所有未确认信息保持透明。

能做什么

• 支持指定目的地单程/往返，以及自由推荐 2–3 个方向。
• 使用高德核验路线、里程、驾驶时间、收费估算和沿途候选地点。
• 收集天气，并将 B 站、小红书材料标记为交叉核验、单平台观察或待补证。
• 将办事、探亲、购物、预约等可选任务放进已有停留日，不挤占驾驶日。
• 生成 index.html 与 trip.generated.js，提供地图、时间轴、文字路书和 Plan B。
• 支持输入指纹、断点续跑、强制重采和可移植 QA。

它不是实时导航或旅行预订服务。出发当天仍需复核导航、天气预警、营业时间、预约和口岸规则。

效果预览

真实路线总览会同时展示逐日时间轴、天气风险、路线里程、社区来源和地点证据状态。

移动端文字路书保留完整逐日信息；桌面端可点击任一城市查看路线事实、候选地点、美食方向和证据状态。

截图来自一次北京—福建 11 天真实数据验收。路线、天气和收费是采集时刻的规划信息，不代表出发当天的实时状态；未完成跨平台核验的店铺仍明确标记为待核验。

一条命令安装

安装到当前用户的 Codex：

curl -fsSL https://raw.githubusercontent.com/leslieyeo/self-drive-planner-skill/main/install.sh | bash -s -- --codex

安装到当前项目，并同时给 Claude Code 建立入口：

curl -fsSL https://raw.githubusercontent.com/leslieyeo/self-drive-planner-skill/main/install.sh | bash -s -- --project "$PWD" --with-claude

安装器默认不会覆盖已有 Skill。确认升级时添加 --force，旧版本会先改名备份。

也可以下载 Releases 中的 ZIP，解压后执行 bash install.sh --codex。

源码池模式

长期维护或多个私人项目共用时，只保留一份 Skill 源码，并让项目按需引用：

GitHub 公开仓库
        ↓ clone / pull
SkillSource/self-drive-planner-skill    唯一代码原件
        ↓ .agents/skills 软链接
私人项目                               密钥、行程、运行状态和生成路书

在源码池中克隆一次：

git clone https://github.com/leslieyeo/self-drive-planner-skill.git /path/to/SkillSource/self-drive-planner-skill

给私人项目启用：

mkdir -p /path/to/private-project/.agents/skills
ln -s /path/to/SkillSource/self-drive-planner-skill \
  /path/to/private-project/.agents/skills/self-drive-planner

SkillSource 只保存通用代码。程序从私人项目目录运行时，默认在该项目中读取和生成：

amap.webservice.local.json
amap.config.local.js
data/
.roadtrip/
trip.generated.js
index.html  → 可链接到 Skill 中的页面模板

功能只在 SkillSource 修改一次；各私人项目不再复制或维护第二份脚本。

首次配置

需要 Node.js 20 或更新版本，以及你自己的高德凭证：

1. 在私人工作区根目录的 amap.webservice.local.json 填入高德 Web 服务 API Key。
2. 在私人工作区根目录的 amap.config.local.js 填入高德 JS API Key 与安全密钥。
3. 编辑私人工作区的 data/trip-request.json，或直接让 Agent 根据自然语言生成它。

安装器复制模式会自带对应 .gitignore；源码池模式请把 templates/workspace.gitignore 中的规则合并到私人项目。.gitignore 不会影响文件留在本机。

基础路线生成不依赖 Playwright。只有需要高德 JS API 降级或页面自动检查时，才在 Skill 源码目录执行：

npm install

使用

在 Codex 或 Claude Code 中：

$self-drive-planner 北京出发，福建往返 11 天，重点吃当地特色并避开人群

源码池/软链接模式下，在私人项目根目录直接运行：

node .agents/skills/self-drive-planner/scripts/run-trip.mjs --skip-community
node .agents/skills/self-drive-planner/scripts/run-trip.mjs --status

安装器复制安装、且当前目录就是 Skill 目录时，也可以运行：

# 基础路线、天气、候选地点和路书
node scripts/run-trip.mjs --skip-community

# 可选：补充社区体验证据
node scripts/run-trip.mjs --community-only

# 完整流程
node scripts/run-trip.mjs

# 忽略断点并强制重采
node scripts/run-trip.mjs --fresh

# 查看当前阶段状态
node scripts/run-trip.mjs --status

本地预览：

python3 -m http.server 8000

然后打开 http://localhost:8000/index.html。

社区数据边界

• B 站使用只读公开搜索。
• 小红书需要 OpenCLI、Browser Bridge 和用户已有登录态。
• 不读取或导出 Cookie，不点赞、评论、收藏或发布。
• 出现验证码时停止并等待人工处理，不绕过验证。
• 社区材料不能替代地图路线、官方营业信息或实时导航。
• 大众点评没有适合普通开发者直接使用的免费公共 API，因此本项目不抓取大众点评数据。

开发与验证

克隆仓库后，无需密钥即可运行通用测试：

npm run check

构建可分发 ZIP：

npm run build

构建产物只包含通用代码、模板和示例，不包含任何本机密钥、登录态或真实行程。

目录结构

SKILL.md              Agent 工作流与安全边界
agents/openai.yaml    Skill 列表展示信息
scripts/              编排、采集、生成与 QA
templates/            本地配置和通用行程模板
data/                 JSON Schema；真实运行数据默认忽略
tests/fixtures/        无密钥通用测试数据
index.html             交互地图路书模板
install.sh             Codex / 项目级一键安装器

隐私与发布

公开仓库不包含原私有仓库的提交历史、旧截图、个人邮箱、真实行程或本地配置。发布自己生成的 index.html 和 trip.generated.js 前，请确认其中的日期与位置可以公开。

.gitignore 只阻止未跟踪文件进入 Git，不会删除本地数据，也不会自动停止跟踪已经提交过的文件。高德密钥必须始终忽略；个人行程是否进入私人 Git 仓库由使用者自行决定。

致谢

项目早期的旅行路书展示思路受到 vibeinging/tool_travel-itinerary 启发。本仓库采用全新历史，不包含该仓库的截图和提交历史。

License

MIT © 2026 leslieyeo