Weekend City Trip · 周末城市旅游攻略调研 Skill

一个让 AI 帮你 5 分钟深度调研任意中国城市周末玩法的 Claude Code/Codex Skill。 基于博查 WebSearch API(博查 API),输出图文并茂、可执行的 Markdown / HTML 攻略。

目录

• 这是什么
• 解决什么问题
• 能调研哪些内容(11 个方向)
• 使用示例
• 生成报告长什么样
• 前置准备
• 安装
• 工作流程(9 步法)
• 项目结构
• 关键能力
• 常见问题
• 限制与边界
• 成本估算
• 贡献
• 许可

这是什么

weekend-city-trip 是一个 [Claude Code/Codex Skill],专门用来做中国城市的周末 / 短期(1 个月内)旅游深度调研。

你只需要对 Claude Code/Codex 说一句话,比如:

"调研下周末广州有什么好玩的"

这个 skill 就会自动:

1. 算清楚"下周末"是哪两天
2. 用博查 API 并行发起 10+ 次中文网页搜索
3. 把搜索结果按 10 节标准结构整合成一份图文并茂的 Markdown 报告
4. 自动质量检查 — 不达标会触发补查询重写(最多 2 轮迭代)
5. (可选)把 Markdown 转成漂亮的 HTML 单文件方便分享

最终交付物是一份 20-30 KB 的城市周末行动方案,覆盖吃、喝、玩、乐、行、住各个维度。

解决什么问题

自己做一份"周末去 XX 城市"的攻略,手动查资料痛点很明显:

能调研哪些内容(11 个方向)

最终整合为 10 节报告:

〇、一图速览(表格)
一、活动全清单(演唱会/集市/球赛/博物馆/5A)
二、优惠门票
三、喜茶门店热点
四、美食街
五、city walk 路线
六、地铁路线(含 5A 景区 + 商场直达)
七、周末组合路线(A/B/C 三条主题路线)
八、时效可靠性说明
九、API 调用统计
十、引用源

使用示例

基础用法(Markdown 输出)

直接对 Claude Code/Codex 说:

调研下周末广州有什么好玩的,要图文版

或者:

我想本周末去上海,帮我全面调查一下

或者:

成都未来一个月旅游调研,情侣向

Claude 会自动触发这个 skill,生成:

D:/fireclaw/广州下周末调查报告_博查版.md

进阶用法(HTML 输出)

加一句"要 HTML":

调研下周末杭州,生成 html 报告

或者用 skill 内部命令:

/weekend-city-trip 杭州,时间下周末,格式 html

会多生成一份单文件 HTML,自带 CSS,浏览器打开直接看,也方便打印为 PDF 分享给朋友。

明确时间 + 偏好

调研上海 7 月 4-5 日,带娃亲子向,要 html

skill 会:

• 把时间锁定为 2026/7/4-7/5(具体日期)
• 在 query 里加"亲子 / 家庭 / 儿童"关键词
• 最终生成 MD + HTML 双格式

生成报告长什么样

典型产出:

• 文件大小:20-30 KB(MD)/ 30-40 KB(HTML)
• 行数:450-550 行
• 图片数:8-12 张代表图
• 信源数:30-50 个权威网站引用

信源优先级:腾讯新闻、网易、人民网、官方文旅局、本地宝、行业垂直媒体(如大麦、猫眼)、小红书高赞笔记。

报告特点:

1. 一图速览 — 10 秒拿到核心情报表格
2. 时间地点完整 — 演出有日期、场馆、票价;景点有票价、地铁
3. 图文并茂 — 每节 1-2 张代表图,图下粗体说明(防图失效)
4. 三条周末路线 — 文艺 / 情侣 / 家庭三种主题,带时间表
5. 二次确认声明 — 票价 / 演出嘉宾可能变动,标注"出行前请二次确认"
6. API 调用透明 — 列出每次调用的 query、freshness、返回条数

前置准备

1. 博查 API Key(必需)

去 博查官网 注册,获取 API Key(格式 sk-xxx)。

新用户通常有免费额度,足够跑 3-5 次完整调研。每次调研消耗约 11-15 次调用。

2. Python(HTML 输出必需)

• Python 3.7+(脚本依赖)
• 推荐安装(完整 GFM 支持):
  copy

  pip install markdown pymdown-extensions
  

• 不装也能用:脚本会自动降级到内置极简转换器,基础表格/代码块/列表都支持

3. curl(已预装)

• Windows 10/11、macOS、Linux 都已预装
• 调用博查 API 用 curl,无需额外装 HTTP 客户端

4. Claude Code/Codex

• 已安装 Claude Code/Codex CLI
• 把本 skill 放到 .claude/skills/weekend-city-trip/(参见安装)

安装

方式 1:克隆到全局 skills 目录

直接命令 claude code/ codex , 帮忙安装skill: github.com/liangdabiao/weekend-city-trip

方式 2:克隆到项目级 skills 目录

# 在你的项目目录下
cd your-project/
mkdir -p .claude/skills/
git clone <your-repo-url> .claude/skills/weekend-city-trip

验证安装

在 Claude Code/Codex 里输入:

/skills

应该能看到 weekend-city-trip 出现在列表里。

设置 API Key(两种方式)

方式 A:环境变量(推荐)

# Linux/macOS
export BOCHA_API_KEY="sk-xxx"

# Windows PowerShell
$env:BOCHA_API_KEY="sk-xxx"

# Windows CMD
set BOCHA_API_KEY=sk-xxx

方式 B:key直接告诉 Codex/Claude code

调研广州下周末,API key 是 sk-xxx

工作流程(9 步法)

skill 内部执行流程,公开透明,方便排查问题。

Step 1:时间锁定

算清楚"本周末/下周末/未来一个月"对应的具体日期。

关键洞察:新闻文章发布时间 ≠ 活动举办时间。一篇 6/26 发布的文章可能在介绍 7/4 的活动,所以 freshness 必须用 oneMonth 拿"近期发布 + 介绍未来活动"的文章。

Step 2:用户确认

如果用户消息里已经有城市 + 时间,直接进入 Step 3。否则用 AskUserQuestion 询问。

Step 3:建任务 + 工作目录

D:/fireclaw/bocha_{城市拼音}/

创建 6 个 TodoTask,跟踪进度。

Step 4:写 query JSON 文件

为每个调查方向写 query body,必须用 heredoc + -d @file.json(Windows curl 坑,详见 pitfalls.md)。

cat > D:/fireclaw/bocha_guangzhou/q1a.json << 'EOF'
{"query":"广州 周末活动 展览 演出 市集 演唱会 2026年7月","summary":true,"count":12,"freshness":"oneMonth"}
EOF

Step 5:4 路并行批次执行

严格 4 路并行(5 个开始触发 429):

curl -s -X POST "$API" -H "Authorization: Bearer $API_KEY" \
  -H "Content-Type: application/json" -d @"$DIR/q1a.json" -o "$DIR/r_q1a.json" &
curl ... -d @"$DIR/q2a.json" -o "$DIR/r_q2a.json" &
curl ... -d @"$DIR/q3a.json" -o "$DIR/r_q3a.json" &
curl ... -d @"$DIR/q4.json" -o "$DIR/r_q4.json" &
wait

11 次调用拆成 4+4+3 三个批次。

Step 6:解析响应

用 Python 单行脚本提取 name / siteName / datePublished / summary / thumbnailUrl 字段。

字段优先级:summary(AI 摘要,核心) > snippet > name(标题)。

Step 7:整合图文报告(初稿)

按 10 节标准结构整合,输出到:

D:/fireclaw/{城市}{时间}调查报告_博查版.md

注意:这只是初稿,不等于任务完成。必须经过 Step 8 质量检查才能交付。

Step 8:质量检查与迭代优化(必做)

这是这个 skill 的核心差异化能力,详见 quality_check.md。

8.1 自动检查

用 Python 脚本扫描初稿,5 大维度:

• 完整性:11 调查方向 + 10 节结构是否齐全
• 准确性:时间/地点/价格是否真实
• 丰富度:每节信息密度是否达标
• 可执行性:周末路线时间是否冲突
• 信源多样性:关键信息是否 ≥ 2 个信源

8.2 各节最低信息密度

8.3 触发补查询(最多 2 轮)

8.4 迭代控制

• 最多 2 轮补查询(防止无限循环)
• 总 API 调用 ≤ 15 次(初始 11 + 补救 4),仍在 50 次预算内
• 第 3 轮仍不达标 → 标注"信息有限"交付

Step 9:HTML 输出(可选)

触发条件:用户明确要求 HTML 格式。

前置条件:Step 8 必须已通过。

python .claude/skills/weekend-city-trip/scripts/md_to_html.py \
  "D:/fireclaw/{城市}{时间}调查报告_博查版.md"

HTML 特性:

• GFM 完整支持(表格/代码块/引用块)
• 内嵌 CSS(单文件可分享,无外部依赖)
• 中文字体优化(苹方/微软雅黑/思源黑体 fallback)
• 响应式布局(手机/平板/桌面自适应)
• 图片 lazy loading
• 打印友好(@media print 样式,可直接打印为 PDF)

项目结构

weekend-city-trip/
├── SKILL.md                          # Skill 主文件(9 步法 + API 用法)
├── README.md                         # 本文件
├── references/
│   ├── query_templates.md            # 11 个方向的 query body 模板
│   ├── report_template.md            # 10 节报告标准结构模板
│   ├── pitfalls.md                   # 12 个踩坑清单 + 决策树
│   └── quality_check.md              # 质量检查 + 补查询迭代规则
└── scripts/
    └── md_to_html.py                 # Markdown → HTML 转换器

各文件作用

关键能力

1. 跨城市标准化

不同城市的博查索引覆盖存在差异(广州 include 过滤失效、上海召回偏低、北京喜茶主题店类型不同...)。skill 用城市前缀 + 多区域关键词应对,不依赖脆弱的 include 过滤。

2. 时效性保障

• 强制 freshness=oneMonth / oneWeek 拿近期文章
• 但理解"发布时间 ≠ 举办时间",允许旧文章介绍未来活动
• 报告末尾标注"出行前请二次确认"

3. 信源可信度

• 优先权威媒体(腾讯/网易/人民网/官方文旅)
• 关键信息(票价/演出嘉宾)要求 ≥ 2 个信源验证
• 信源清单完全公开,报告末尾按任务分类列引用

4. 反幻觉

• 不编造未在 summary / snippet 中出现的信息
• 单源可疑数据标注或删除
• 图片 URL 检测失效,失效则替换为文字说明

5. 质量保障闭环

报告生成 ≠ 任务完成。Step 8 强制检查 + 最多 2 轮迭代优化,确保交付质量稳定。详见 quality_check.md。

6. 失败优雅降级

• markdown 库没装 → markdown2 → 兜底内置转换器
• include 过滤失效 → 改用 query 前缀
• freshness 太严召回少 → 降级到 noLimit
• summary 字段空 → snippet / name 兜底
• 图片 URL 相对路径 → 自动补 https:

常见问题

Q1:一定要博查 API 吗?可以用 Google/Bing 吗?

目前仅支持博查。原因:

• 博查对中文索引覆盖最佳
• summary 字段(AI 摘要)极大减少 token 消耗
• freshness + include 参数适合旅游场景

后续可能扩展 Exa / Tavily 等中文友好搜索 API。

Q2:支持海外城市吗?

不支持。博查以中文索引为主,海外城市召回极低。海外场景请用其他通用 web search skill。

Q3:每次调研消耗多少 API 额度?

11-15 次调用(初始 11 + 补救 4)。博查新用户通常有免费额度,够跑 3-5 次。

Q4:生成的报告可以商用吗?

报告内容来自公开网页,版权归原作者。调研结果仅供个人参考,商用请自行核实版权。

Q5:HTML 转换一定要装 markdown 库吗?

不装也能用。脚本三档优先级:

1. python-markdown(完整 GFM)
2. markdown2(次选)
3. 内置兜底转换器(基础支持,无需任何外部库)

但强烈推荐装 pip install markdown pymdown-extensions,完整 GFM 表格、代码高亮、任务列表等特性才完整。

Q6:为什么 11 个方向拆成 6 个 TodoTask?

平衡信息密度与执行效率。同类方向(如演唱会 + 集市 + 球赛)合并到一个任务,既避免任务碎片化,又保持清晰度。

Q7:为什么严格 4 路并行,不是 8 路?

实测 5 个并行开始触发 429(频率超限)。4 路稳定,留 1-2 个 slot 给补救重试。详见 pitfalls.md 坑 2。

Q8:报告里有"二次确认"提示,是不是数据不可靠?

部分信息可能时效性偏弱(如地铁出口编号、票价微调)。skill 已经做了多源验证,但仍建议:

• 演出票务:出行前到大麦 / 猫眼二次确认
• 景区票价:出行前到官方公众号二次确认
• 营业时间:出行前到大众点评二次确认

限制与边界

✅ 适用场景

• 中国大陆城市调研
• 周末 / 1 个月内短期旅游
• 任意 4-7 线及以上城市(北上广深、成都、杭州、武汉、西安、南京...)

❌ 不适用场景

• 海外城市(请用通用 web search)
• 长期旅居 / 移民调研(超过 1 个月)
• 单一深度主题(如只查某场演唱会票价 → 直接 WebSearch 即可)
• 极端小众县城(博查索引可能覆盖不足)

已知限制

• 博查索引覆盖不均(不同城市召回数量波动 5-15 条)
• 长尾信息(地铁出口编号)文章偏旧(2018-2022),但出口编号基本不变
• 视频搜索未开放,图文替代
• 不支持 JS 渲染(复杂 SPA 网页摘要可能不全)

成本估算

时间成本

API 额度

• 初始:11 次调用
• 补救:0-4 次(视触发条件)
• 总计:11-15 次

博查定价请见官网。新用户通常有免费额度,够跑 3-5 次完整调研。

贡献

欢迎 PR / Issue。特别欢迎以下贡献:

• 新城市的 query 模板优化(不同城市关键词差异)
• 报告结构的本地化适配(如港台场景)
• HTML 模板美化(当前是 GitHub 风格,可加更多主题)
• 翻译为英文(海外华人用户)

许可

MIT License — 详见 LICENSE。

一句话总结

说一句话 → 11-15 次博查 API 调用 → 7-15 分钟 → 20-30 KB 图文攻略 → 覆盖吃 / 喝 / 玩 / 乐 / 行的 10 节标准报告 + 三条周末路线。

让 AI 帮你把"周末去哪玩"的攻略难题,变成一句话的事。

特别感谢：

https://linux.do 社区佬友 https://open.bochaai.com/ 博查 API 提供方