# 零基础跑通指南：从装好到拿到第一份路书

> 这份教程写给**完全没接触过 AI 助手**的你。全程跟着做，大约 30 分钟。
> **两条路线任选**：A=Claude Code（功能最全，推荐）；B=任意 AI 助手（Kimi/DeepSeek/通义千问/文心一言等，不装新软件）。路线 B 从「第 1.5 步」开始。
> 卡住了拉到底部看 FAQ，还不行就去 [Issues 提问](https://github.com/awangwang123/jianhao-travel-planner/issues)。

---

## 第 0 步 · 开始前你要知道的三件事

1. **这是一个「技能包」，不是 App**——它装进 AI 助手，让 AI 学会做旅行路书。所以你要先有一个 AI 助手（任何一个都行），再装技能。
2. **需要一台电脑**（Windows 或 Mac）。手机上看成品路书没问题，但跑生成这一步需要电脑。
3. **费用诚实说明**：技能包本身免费开源；运行它的 AI 助手按各家收费——路线 A=Claude 订阅（Pro 约 $20/月）或 API 按量付费（做一份路书通常几块钱人民币级）；路线 B=你已在用的 AI 助手费用（多数有免费档）。

---

## 第 1 步 · 准备你的 AI 助手（二选一）

**路线 A=下面的 Claude Code 安装教程（Windows/Mac）**｜**路线 B=任意 AI 助手，跳过本步直接看下面的「第 1.5 步」**

### Windows（路线 A）

1. 装 Node.js：打开 [nodejs.org](https://nodejs.org/)，下载 **LTS 版**，双击安装，一路「下一步」
2. 按 `Win 键`，输入 `powershell`，回车，打开蓝色终端窗口
3. 输入下面这行，回车：

```
npm install -g @anthropic-ai/claude-code
```

4. 装完后输入 `claude` 回车——第一次会引导你用浏览器登录 Claude 账号，跟着点完即可
5. 看到 `>` 提示符 = 成功 ✅

### Mac

1. 装 Node.js：同上（nodejs.org 下载 LTS）
2. 打开「终端」（启动台搜索 Terminal）
3. 同样执行 `npm install -g @anthropic-ai/claude-code`，装完输入 `claude` 登录

> ✅ **自检**：输入 `claude` 后出现一个可对话的界面，就说明装好了。报「不是内部或外部命令」→ 重启终端再来一次，还不行重装 Node。

---

## 第 1.5 步 · 路线 B：任意 AI 助手通用装法（不装新软件）

Kimi / DeepSeek / 通义千问 / 文心一言 / Cursor / 其他——只要你的 AI 能读长文本，就能用本技能包。

1. 下载本仓库（绿色 `Code` 按钮 → Download ZIP），解压
2. 打开你的 AI 助手（网页版/客户端均可），新开对话
3. 把 `SKILL.md` 全文贴给 AI，然后补一句开工口令：

```
你是我的旅行规划助手。请完整阅读上面这份 SKILL.md 并严格按其中的流程工作。
我要做一次旅行：【目的地+天数+出发地+人数，一次说全】。
```

4. AI 交付路书 HTML 后，保存成 `.html` 文件，双击用浏览器打开
5. 验收照「第 6 步」走：把 `tools/checklist.py` 的跑法结果贴回给 AI，要求修到全 PASS 再定稿

> 两条路线的差别只在「交付闸门怎么强制执行」：路线 B 靠你把检查结果贴回去人工把关；路线 A 可装 hooks 让系统自动拦（见文末进阶）。**技能条款是同一套，但执行效果取决于 AI 助手的能力**——路线 A（Claude Code）为已验证环境：能联网读写文件并运行脚本，可完整走通全流程；路线 B 的 AI 助手需具备同等能力才能完整使用，仅能对话的助手不保证同等效果。

## 第 2 步 · 下载旅行规划器

1. 打开仓库右侧 **Releases** 区（或 [点这里](https://github.com/awangwang123/jianhao-travel-planner/releases)）
2. 下载最新版的 **`jianhao-travel-planner_vX.X.zip`**
3. **解压**（右键 → 全部解压），得到一个 `jianhao-travel-planner` 文件夹——**别改名**

---

## 第 3 步 · 放进 skills 目录（最关键的一步）

把整个 `jianhao-travel-planner` 文件夹**复制**到下面对应目录（文件夹不存在就自己新建一个，名字必须是 `skills`）：

| 系统 | 路径（全局，推荐） |
|------|------|
| Windows | `C:\Users\你的用户名\.claude\skills\` |
| Mac | `~/.claude/skills/` |

> 💡 找不到 `.claude` 文件夹？它是隐藏文件夹。Windows 资源管理器地址栏**直接粘贴** `C:\Users\你的用户名\.claude\skills` 回车即可（用户名换成你自己的，开机登录显示的那个）。

放好后路径应该是：

```
…\skills\jianhao-travel-planner\SKILL.md   ← 有这个文件就对了
```

> ⚠️ **最常见的失败原因**：多套了一层文件夹（变成 `skills\jianhao-travel-planner\jianhao-travel-planner\SKILL.md`）——SKILL.md 必须在第一层。

---

## 第 4 步 · 第一次生成路书

1. **关掉并重新打开**终端，输入 `claude` 回车
2. 直接对人话，比如：

> 「周末想去武汉玩两天，帮我做一份攻略，两个人，高铁往返」

3. AI 会反过来问你几个问题（预算档位 / 想热闹还是清静 / 有没有忌口之类）——**想到什么说什么，不用专业**
4. 然后它会自己联网查资料、规划、生成——**耗时取决于行程天数、实查深度与返工次数，没有固定值**（从十几分钟到更久都有），期间可以去干别的
5. 完成后它会告诉你文件存在哪（通常在它的工作目录里，文件名带「路书」）

> ✅ **自检**：AI 提到了「路书」文件路径 = 成功。

---

## 第 5 步 · 打开与分享路书

- **自己看**：找到那个 `.html` 文件，**双击**——会用浏览器打开（推荐 Chrome / Edge）
- **发朋友**：微信直接传这个 `.html` 文件，朋友手机点开选「用浏览器打开」，或电脑双击——**单文件、断网也能看**
- ⚠️ 传文件时**别改文件名**（尤其别去掉 `.html` 后缀），改了就打不开了
- 文件有 2~3MB，手机上打开需要几秒加载，属正常

---

## 第 6 步 · 验收你的 AI 交的货（别照单全收）

AI 交了路书 ≠ 路书合格。本包自带一个机械检查脚本，一行命令验收：

```bash
python tools/checklist.py 你的路书.html --visual
```

它会跑一套机械检查清单（检查项随版本演进，以工具实际输出为准）：区块是否齐全非空、每天早午晚餐行是否齐、有没有模板占位符残留、JS 是否拼接错误、桌面和手机有没有排版溢出……

- 全部 ✅ = **机械检查通过**——版式、区块与流程完整性有底线保障；**交通、票务、价格等关键事实仍须按路书内的核实状态标注复核**，机械检查不替代事实核验
- 有 ❌ = 把输出**原样贴回给 AI**，说「修复这些 FAIL 再交」——AI 也会偷懒，这个脚本就是你的验收武器

---

## 进阶：给 AI 上锁（可选，新手可跳过）

第 6 步的验收靠你手动跑脚本。如果你想**强制** AI 每次交稿前必须跑过检查（不跑就拦住），Claude Code 的 hooks 机制可以做到：

1. 打开（没有就新建）`~/.claude/settings.json`，加入：

```json
{
  "hooks": {
    "Stop": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "python ~/.claude/skills/jianhao-travel-planner/tools/checklist.py \"$(find . -maxdepth 2 -name '*路书*.html' -newer ~/.claude/skills/jianhao-travel-planner/SKILL.md | head -1)\" || echo '⚠️ checklist 未通过——请先修复再结束'"
          }
        ]
      }
    ]
  }
}
```

2. 重启 Claude Code 生效。之后 AI 每次想结束任务，系统都会自动跑一遍检查——没过就提醒它修复。

> 说明：①仅 Claude Code 用户可用（其他 AI 助手有自己的机制）②路径按你的实际安装位置调整 ③这是「最接近真强制」的手段——不靠 AI 自觉，靠运行时拦截 ④新手可跳过，第 6 步的手动验收已经够用

---

## 常见问题 FAQ

**Q1：输入 claude 报「不是内部或外部命令」？**
Node.js 没装好，或装完没重开终端。重装 Node → 重开终端再试。

**Q2：说了触发词，AI 没反应/不会做路书？**
九成是路径放错。核对：`skills\jianhao-travel-planner\SKILL.md` 是否第一层；文件夹名是否被改过。

**Q3：路书文件双击打不开 / 打开是乱码？**
①确认后缀还是 `.html`（微信传输有时会改名）②用 Chrome 或 Edge 打开（右键 → 打开方式）③手机上：把文件发到手机，用浏览器打开。

**Q4：要花多少钱？**
技能包免费。AI 助手费用见第 0 步第 3 条——Claude Pro 订阅或 API 按量（做一份路书的 API 成本通常几块钱人民币级）。

**Q5：生成一份要多久？**
耗时取决于行程天数、实查深度与返工次数，没有固定值。它会真的去联网查票价、营业时间、天气——慢是特性不是卡了。

**Q6：数据靠谱吗？**
关键信息联网实查带来源，天气按出发前 3 天终判；但价格、营业时间以现场为准，路书里都会标注。

**Q7：可以直接问它问题吗（不做路书）？**
可以。装好后它就是「懂做攻略的助手」——问「武汉过早吃什么」它也会按实查习惯回答。

**Q8：手机上能跑吗？**
跑生成需要电脑；成品路书手机电脑都能看。

---

## 进阶（可选）

- **在线版部署**：有自己的服务器的话，可以让 AI 把路书瘦身并部署成网址（见 SKILL.md）
- **玩法深入**：`SKILL.md` 的版本史是精华——每条规矩背后都是一次真实翻车

---

## 反馈与许愿

- 🐛 **用不了/报错**：去 [Issues](https://github.com/awangwang123/jianhao-travel-planner/issues) 发帖，贴上报错截图
- 📍 **许愿城市**：想看哪里的路书？去 Discussions 的「旅行许愿池」留言——点赞最高的城市，下一份官方示例就是它
- 你的每一条反馈都会变成技能包的下一次升级