Skip to content
Back to search

weekend-city-trip

workbuddy/ codex skill , 一个让 AI 帮你 5 分钟深度调研任意中国城市周末玩法的agent skill, 寻找精神旷野:户外消费告别长途远行、装备内卷,转向日常低成本微沉浸;菜市场、城市老街成为年轻人精神微旅行目的地,CityWalk 演化成主题探索路线,日常场景即可实现情绪解压。

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/liangdabiao--weekend-city-trip/badge.svg)](/listings/liangdabiao--weekend-city-trip)

HTML

<a href="/listings/liangdabiao--weekend-city-trip"><img src="/api/listings/liangdabiao--weekend-city-trip/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

方式 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 是否生效

# 验证 anysearch
echo $ANYSEARCH_API_KEY  # 应输出 as_sk-xxx(无 key 也可走 anonymous)

# 验证高德(可选,仅地图生成需要)
echo $AMAP_KEY $AMAP_JS_KEY $AMAP_SECURITY

更详细的 Key 配置见下方 [API Key 配置](#api-key-配置必读) 章节。

---

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

SKILL.md · Manifest · 663 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. ---
  2. name: weekend-city-trip
  3. description: Comprehensive weekend city travel investigation skill for Chinese cities. Use this skill PROACTIVELY whenever the user wants to research a city for weekend or near-future (within 1 month) travel — including 小红书 activities, 演唱会/concerts, 集市/markets, 球赛/sports matches, 博物馆/museums, 优惠门票/discount tickets, 喜茶门店/Heytea locations, 美食街/food streets, city walk routes, 5A 景区/scenic areas, and 地铁路线/subway routes. Triggers on phrases like "调研XX城市"、"XX城市周末去哪"、"周末小旅游"、"XX城市旅游攻略"、"本周末/下周末去XX"、"XX城市近期活动"、"weekend trip to [city]"、"investigate [city]"、"城市调查". Search via anysearch CLI. All judgment, extraction, and writing done by the runtime agent (you) — no external LLM API calls. Generates text-only Markdown reports (no inline images; anysearch `search` does not return thumbnailUrl). Always invoke this skill when the user mentions researching any Chinese city for short-term travel, even if they don't explicitly ask for a "skill" or "攻略".
  4. ---
  5. # 周末城市旅游攻略调研 Skill
  6. 基于 **anysearch WebSearch API** 的标准化城市旅游调研工作流,支持任意中国城市的本周末 / 下周末 / 未来一个月深度调研。
  7. > **后端分工**:
  8. > - 搜索 (Step 4-5) → **anysearch CLI**
  9. > - 地点抽取 / 判断 / 清理 (Step 10) → **runtime agent 本体**(你读 markdown 自己干,**不调任何外部 LLM**)
  10. > - 地图 (Step 10) → **高德 AMAP**
  11. >
  12. > **报告格式**: 纯文字版 (无内嵌图,改用 emoji + 表格 + 粗体强调)。anysearch `search` 不返回 thumbnailUrl。
  13. 覆盖 11 个调查方向:小红书近期活动、演唱会、集市、球赛、博物馆、优惠门票、喜茶门店、美食街、city walk、5A 景区、地铁路线。生成结构化的 Markdown 攻略,信源以权威媒体为主(腾讯新闻、网易、人民网、官方文旅、本地宝、行业媒体等)。
  14. ---
  15. ## 适用场景
  16. ✅ **适用**:
  17. - "调研广州下周末有什么好玩"
  18. - "上海本周末活动攻略"
  19. - "成都未来一个月旅游调研"
  20. - "北京周末小旅游"
  21. - "我想下周末去杭州,帮我全面调查一下"
  22. ❌ **不适用**:
  23. - 海外城市调研
  24. - 长期旅居 / 移民调研(超过 1 个月)
  25. - 单一深度主题(如只查某场演唱会票价 → 直接 WebSearch 即可)
  26. ---
  27. ## 前置准备
  28. 执行前必须确认 3 项:
  29. | 项 | 说明 | 默认 |
  30. |---|---|---|
  31. | **Anysearch API key** | 用户提供 `as_sk-xxx` (anonymous 也可,QPS 低) | — |
  32. | **目标城市** | 中文城市名(广州/上海/成都...) | — |
  33. | **时间范围** | 本周末 / 下周末 / 未来一个月 / 具体日期 | 下周末 |
  34. | 偏好(可选) | 亲子/情侣/独行/带娃 | 通用 |
  35. | **报告格式** | 纯文字版(emoji + 表格 + 粗体) | 文字版 |
  36. | **输出格式**(可选) | markdown / html / both | markdown |
  37. | **工作目录**(可选) | 报告/地图输出目录,环境变量 `OUTPUT_DIR` | `D:/fireclaw-travel` |
  38. 如果用户没说时间范围,**默认下周末**(本周可能来不及准备)。
  39. ### API Key 配置
  40. 本 Skill 需要以下 API Key,推荐通过 `.env` 文件配置(已在 `.gitignore` 中排除,不会泄露):
  41. | 变量名 | 用途 | 申请地址 |
  42. |--------|------|----------|
  43. | `ANYSEARCH_API_KEY` | Anysearch WebSearch API(搜索调研) | https://anysearch.com/console/api-keys |
  44. | `AMAP_KEY` | 高德 Web 服务 API(地理编码) | https://console.amap.com/dev/key/app(类型选「Web 服务」) |
  45. | `AMAP_JS_KEY` | 高德 Web 端 JS API(浏览器加载地图底图) | https://console.amap.com/dev/key/app(类型选「Web 端(JS API)」 |
  46. | `AMAP_SECURITY` | 高德安全密钥(与 JS API Key 配套) | 高德控制台 Key 详情页 |
  47. | `OUTPUT_DIR` | 报告/地图输出目录(可选) | 默认 `D:/fireclaw-travel` |
  48. | `VERBOSE` | 详细日志输出(可选,`1`/`true`/`yes`) | 默认关闭 |
  49. **配置方式**:
  50. ```bash
  51. # 方式 1: .env 文件(推荐,持久化)
  52. cp .env.example .env
  53. # 编辑 .env 填入你的 Key
  54. # 方式 2: 环境变量(临时)
  55. export ANYSEARCH_API_KEY="as_sk-xxx"
  56. export AMAP_KEY="xxx"
  57. export AMAP_JS_KEY="xxx"
  58. export AMAP_SECURITY="xxx"
  59. ```
  60. > **安全提醒**: 绝不要把 `.env` 文件或真实 Key 提交到版本库。`.env.example` 仅为模板,不含真实密钥。
  61. ---
  62. ## 工作流程(10 步法)
  63. ### Step 1: 时间锁定
  64. 算清楚用户的"本周末/下周末"对应的具体日期:
  65. - 今天 = `{currentDate}`
  66. - 本周末 = 即将到来的周六周日
  67. - 下周末 = 下一个周六周日
  68. - "未来一个月" = 今天起 30 天内
  69. **关键洞察**:新闻文章发布时间 ≠ 活动举办时间。一篇 6/26 发布的文章可能在介绍 7/4 的活动。anysearch 没有 `freshness` 字段,改用 query 里加 `2026年7月`/`近期`/`本周末` 等关键词隐式表达"近期发布 + 介绍未来活动"的文章。
  70. ### Step 2: 用户确认
  71. 如果用户消息里已经包含城市 + 时间,直接进入 Step 3。
  72. 否则用 AskUserQuestion 确认。
  73. ### Step 3: TaskCreate + 工作目录
  74. 工作目录用 `$OUTPUT_DIR` 表示,默认为 `D:/fireclaw-travel`,可通过环境变量 `OUTPUT_DIR` 覆盖。
  75. ```
  76. $OUTPUT_DIR/anysearch_{城市拼音}/
  77. ```
  78. **变量约定**:
  79. - `$OUTPUT_DIR` — 报告/地图输出目录(默认 `D:/fireclaw-travel`)
  80. - `$SKILL_DIR` — 本 Skill 所在目录(即本文件所在目录,anysearch CLI 已内置在 `$SKILL_DIR/scripts/`)
  81. TaskCreate 6 个任务(信息密度与执行效率的平衡点):
  82. 1. {城市}近期活动(活动/演唱会/集市/球赛/博物馆)
  83. 2. {城市}优惠门票(本地宝优惠 + 5A 景区)
  84. 3. {城市}喜茶热点(门店 + 购物中心)
  85. 4. {城市}美食街 + city walk
  86. 5. {城市}地铁路线(线网 + 关键站点出口)
  87. 6. 整合 {城市}纯文字报告
  88. ### Step 4: 写 query JSON 文件
  89. 按 `references/query_templates.md` 为每个调查方向写 query body(11 个 query 模板)。anysearch 字段简单,只有 `query` + `max_results`(1-10):
  90. ```json
  91. {"query":"广州 周末活动 展览 演出 市集 演唱会 2026年7月","max_results":10}
  92. ```
  93. > 完整 query 体见 `references/query_templates.md`(11 模板)。
  94. ### Step 5: 并行批次执行(anysearch CLI)
  95. anysearch `batch_search` 一次支持 1-5 并行,11 个 query 拆 3 批:
  96. ```bash
  97. ANYSEARCH="python $SKILL_DIR/scripts/anysearch_cli.py"
  98. DIR="$OUTPUT_DIR/anysearch_{城市拼音}"
  99. # 批次 1(5 路并行:1a+1b+1c+1d+2a)
  100. $ANYSEARCH batch_search --queries '[
  101. {"query":"{CITY} 周末活动 展览 演出 市集 演唱会 2026年7月","max_results":10},
  102. {"query":"小红书 {CITY} 拍照 网红 打卡 同城活动 暑期","max_results":10},
  103. {"query":"{CITY} 7月 演唱会 集市 球赛 体育 周末去哪 最新","max_results":10},
  104. {"query":"{CITY} 博物馆 推荐 5A 景区 必去 打卡 2026","max_results":10},
  105. {"query":"{CITY} 景区 门票 优惠 暑期 学生 考生 特惠","max_results":10}
  106. ]' > "$DIR/r_batch1.json"
  107. # 批次 2(4 路:3a+3b+4a+4b)
  108. $ANYSEARCH batch_search --queries '[
  109. {"query":"{CITY} 喜茶 旗舰店 打卡 购物中心 黑金店 2026","max_results":10},
  110. {"query":"{CITY} 喜茶 lab店 DP店 主题店 推荐","max_results":10},
  111. {"query":"{CITY} 美食街 推荐 夜市 区域 2026","max_results":10},
  112. {"query":"{CITY} city walk 路线 推荐 老城区 历史街区","max_results":10}
  113. ]' > "$DIR/r_batch2.json"
  114. # 批次 3(2 路:5a+5b)
  115. $ANYSEARCH batch_search --queries '[
  116. {"query":"{CITY} 地铁 线路图 2026 最新 主要区域","max_results":10},
  117. {"query":"{CITY}地铁 站点 出口 地标 商场","max_results":10}
  118. ]' > "$DIR/r_batch3.json"
  119. ```
  120. **响应解析**(anysearch 返回 JSON-RPC `result.content[].text` 纯文本):
  121. ```python
  122. import json, sys, io
  123. sys.stdout = io.TextIOWrapper(sys.stdout.buffer, encoding='utf-8')
  124. for f in ['r_batch1.json', 'r_batch2.json', 'r_batch3.json']:
  125. with open(f, encoding='utf-8') as fp:
  126. d = json.load(fp)
  127. for item in d.get('result', {}).get('content', []):
  128. if item.get('type') == 'text':
  129. print(f'==={f}===')
  130. print(item['text'][:2000]) # 截前 2000 字符预览
  131. break
  132. ```
  133. ### Step 6: 解析响应
  134. anysearch 响应是 JSON-RPC 文本流,**无 `summary` / `data.images` 字段**。文本以 `--- 标题: ...\nURL: ...\n摘要: ...` 分隔。
  135. 整合报告时按这个分隔符切分,每个 result 块包含标题、URL、摘要三段。
  136. > **注意**: anysearch 路径下**不嵌入外部图片**(`search` 响应无 `thumbnailUrl`)。报告改为纯文字版:emoji + 表格 + 粗体强调。
  137. ### Step 7: 整合文字报告(初稿)
  138. 按 `references/report_template.md` 的 10 节标准结构整合,输出到:
  139. ```
  140. $OUTPUT_DIR/{城市}{时间}调查报告_Anysearch版.md
  141. ```
  142. **注意**:这只是初稿,**不等于任务完成**。必须经过 Step 8 质量检查与迭代优化才能交付。
  143. ---
  144. ### Step 8: 质量检查与迭代优化(必做)
  145. **报告生成 ≠ 任务完成**。必须按 `references/quality_check.md` 的清单检查并修复。
  146. #### 8.1 自动检查(2 分钟)
  147. 用 python 脚本扫描初稿,5 大维度:
  148. - **完整性**:11 调查方向 + 10 节结构是否齐全
  149. - **准确性**:时间/地点/价格是否真实(演出日期在未来,地铁站存在)
  150. - **丰富度**:每节信息密度是否达标
  151. - **可执行性**:周末路线时间是否冲突,地铁换乘是否合理
  152. - **信源多样性**:是否多源验证(关键信息 ≥ 2 个信源)
  153. 脚本模板见 `references/quality_check.md` 第 8 节。
  154. #### 8.2 各节最低信息密度
  155. | 章节 | 最低 | 优秀 |
  156. |---|---|---|
  157. | 演唱会/演出 | 3 场 | 5+ 场含时间/场馆/票价 |
  158. | 博物馆 | 3 个 | 5+ 个含当前展览 |
  159. | 5A 景区 | 2 个 | 4+ 个含票价/交通 |
  160. | 优惠门票 | 3 个景区 | 5+ 个含原价/现价/规则 |
  161. | 喜茶门店 | 2 家主题店 | 3+ 家含开业日期/产品 |
  162. | 美食街 | 3 条 | 5+ 条含区域/代表店 |
  163. | city walk | 1 条路线 | 2+ 条含节点/长度 |
  164. | 地铁出口 | 2 个站点 | 4+ 站点含 A/B/C/D 编号 |
  165. | 直达商场 | 5 个 | 10+ 个含地铁站 |
  166. #### 8.3 错误识别与修复
  167. | 问题类型 | 表现 | 修复方式 |
  168. |---|---|---|
  169. | **信息缺失** | 某节 < 最低要求 | 触发补查询(见 8.4) |
  170. | **跨城市噪声** | 提到其他城市 | 删除条目,query 加城市前缀重查 |
  171. | **过时数据** | 2018-2020 票价 | 标注"出行前请二次确认"或重查 |
  172. | **虚假信息(摘要幻觉)** | 数字可疑、单源、矛盾 | 至少 2 个信源验证,否则删除 |
  173. | **路线冲突** | 时间重叠/不可能换乘 | 重新设计路线 |
  174. #### 8.4 补查询触发条件
  175. **任一条件命中就触发补查询**(详见 `references/quality_check.md` 第 5 节):
  176. 🔴 **必补**(不补不能交付):
  177. - 11 个调查方向有任何一个完全缺失
  178. - 演唱会/演出章节 < 3 场
  179. - 演出缺时间或场馆
  180. - 优惠门票章节 < 3 个景区
  181. - 跨城市噪声 > 30%
  182. 🟡 **建议补**(补了显著提升质量):
  183. - 喜茶门店 < 2 家
  184. - 美食街 < 3 条
  185. - city walk 无具体路线
  186. - 地铁出口细节 < 2 个站点
  187. - 关键价格无信源支持
  188. 🟢 **可选**:
  189. - 直达商场清单 < 5 个
  190. #### 8.5 补查询执行
  191. 补查询走 anysearch batch_search (1-5 并行),模板见 `references/quality_check.md` 第 6 节。常用模板:
  192. ```bash
  193. # 演出不足
  194. $ANYSEARCH batch_search --queries '[{"query":"{CITY} 演唱会 2026年7月 排期 时间 场馆 票价 大麦","max_results":10}]'
  195. # 门票不足
  196. $ANYSEARCH batch_search --queries '[{"query":"{CITY} 景区 门票 优惠 学生 暑期 {景区1} {景区2}","max_results":10}]'
  197. # 喜茶门店不足
  198. $ANYSEARCH batch_search --queries '[{"query":"{CITY} 喜茶 门店 地址 营业时间 推荐 {区域1}","max_results":10}]'
  199. # 跨城市噪声严重 → 加强城市前缀
  200. $ANYSEARCH batch_search --queries '[{"query":"{CITY} {CITY} {CITY} {主题} 必去 本地 仅限 {CITY}","max_results":10}]'
  201. ```
  202. #### 8.6 迭代控制
  203. - **最多 2 轮补查询**(防止无限循环)
  204. - 每轮 ≤ 5 次(1 个批次)
  205. - 总 API 调用 ≤ 16 次(初始 11 + 补救 5)
  206. - 第 3 轮触发条件仍命中 → 标注"信息有限"交付,并在报告中说明
  207. #### 8.7 二次检查
  208. 修复后**必须再次扫描**,确认所有 🔴 必补触发条件已解除。如仍有问题,进入第 2 轮迭代。
  209. #### 8.8 修复优先级
  210. 1. **删除跨城市噪声条目**(错误信息会误导用户)
  211. 2. **删除过时数据**(2020 年前的票价/已闭店)
  212. 3. **补充缺失章节**(必补触发)
  213. 4. **补充低密度章节**(建议补触发)
  214. 5. **加二次确认安全声明**(无法验证的信息)
  215. #### 8.9 交付
  216. 所有 🔴 必补触发条件解除后,告知用户:
  217. - 文件路径
  218. - 核心亮点
  219. - API 调用统计(初始 N 次 + 补救 M 次 = 总 N+M 次)
  220. - 已知限制(如有,如"地铁出口信息偏旧,建议二次确认")
  221. ---
  222. ### Step 9: HTML 输出(可选,条件触发)
  223. **触发条件**:用户明确要求 HTML 格式(如"生成 html"、"给我网页版"、"输出 html 报告")。
  224. **前置条件**:Step 8 质量检查必须已通过,Markdown 报告为最终交付版。
  225. #### 9.1 检查 Python 依赖
  226. ```bash
  227. python -c "import markdown" 2>&1 || pip install markdown pymdown-extensions
  228. ```
  229. 如不愿安装,脚本会自动降级到 `markdown2`,再降级到内置极简转换器(无需任何外部库)。
  230. #### 9.2 执行转换
  231. ```bash
  232. python $SKILL_DIR/scripts/md_to_html.py \
  233. "$OUTPUT_DIR/{城市}{时间}调查报告_Anysearch版.md"
  234. # 默认输出同名 .html 文件,也可指定第二参数:
  235. # python md_to_html.py input.md output.html
  236. ```
  237. #### 9.3 HTML 特性
  238. - **GFM 完整支持**:表格、代码块、引用块、有序/无序列表
  239. - **中文字体优化**:苹方 / 微软雅黑 / 思源黑体 fallback
  240. - **响应式布局**:手机 / 平板 / 桌面自适应
  241. - **内嵌 CSS**:单文件可分享,无外部依赖
  242. - **打印友好**:`@media print` 样式,可直接浏览器打印为 PDF
  243. - **纯文字版样式**:emoji + 表格 + 粗体强调替代图片(因 anysearch 无 `thumbnailUrl` 响应)
  244. #### 9.4 交付
  245. 告知用户:
  246. - Markdown 源文件路径
  247. - HTML 文件路径(本次新增)
  248. - 推荐查看方式:浏览器打开,或打印为 PDF 分享
  249. ---
  250. ### Step 10: 地图面板生成(可选,条件触发)
  251. **触发条件**:用户明确要求生成地图(如"生成地图"、"标注在地图上"、"地图版"、"mark on map")。
  252. **前置条件**:Step 8 质量检查必须已通过,Markdown 报告为最终交付版。
  253. **核心原则:地点抽取与判断全部由 runtime agent 本体(你)完成,不调任何外部 LLM API。**
  254. #### 10.1 一键管线(build_map.sh)
  255. 可用 `build_map.sh` 一键执行完整管线(需要设置环境变量):
  256. ```bash
  257. export AMAP_KEY="..." # 高德 Web 服务 Key
  258. export AMAP_JS_KEY="..." # 高德 Web 端 JS API Key
  259. export AMAP_SECURITY="..." # 高德安全密钥
  260. bash $SKILL_DIR/scripts/build_map.sh 金华 "未来一个月" \
  261. -m "$OUTPUT_DIR/金华未来一个月调查报告_Anysearch版.md"
  262. ```
  263. 该脚本自动执行以下 4 步,已完成步骤自动跳过:
  264. ```
  265. Markdown 报告(.md)
  266. ↓ Step 1: agent 抽取地点 你(runtime agent)读 markdown,逐节识别真实地点,
  267. │ 排除食物名/活动名/描述,写 places.json
  268. places.json
  269. ↓ Step 2: geocode.py 高德 REST 批量地理编码→ geo.json
  270. places.geo.json
  271. ↓ Step 3: inject.py 模板替换→ 地图 HTML
  272. {城市}地图_Anysearch版.html
  273. ↓ Step 4: validate_map.py 自动验证地图质量
  274. ```
  275. > **Step 1 由 runtime agent 完成**:你直接读 markdown,逐节识别真实地点,排除食物名/活动名/广告文案等噪声,写 places.json。Step 2-4 才走脚本。
  276. **核心决策**:坐标在**服务端预编码**写入 JSON。HTML 打开时只渲染,不调任何外部 API。
  277. 优势:
  278. - 双击 HTML 即可,**不依赖 http 服务器**(file:// 也正常)
  279. - 不受浏览器 QPS / 配额限制
  280. - HTML 体积小、加载快、可离线分享
  281. #### 10.2 高德 Key 要求(两种 Key,必须用户提供)
  282. **Skill 不内置任何 Key**。用户需到 [高德开放平台](https://console.amap.com/dev/key/app) 申请以下两类 Key:
  283. | 用途 | Key 类型 | 环境变量 | 说明 |
  284. |---|---|---|---|
  285. | HTML 地图底图加载 | **Web 端 (JS API)** | `AMAP_JS_KEY` | 应用类型选「Web 端(JS API)」 |
  286. | JS API 安全密钥 | (与 JS API Key 配套) | `AMAP_SECURITY` | 2021-12-02 后申请的 Key 必须配置 |
  287. | Python 服务端地理编码 | **Web 服务** | `AMAP_KEY` | 应用类型选「Web 服务」(REST 端点) |
  288. **两类 Key 不能互通**:JS API Key 调 REST 会报 `USERKEY_PLAT_NOMATCH`,反之亦然。
  289. **配置方式**(任选其一):
  290. ```bash
  291. # 方式 A:bash / git-bash 环境变量(推荐,持久化到 shell 配置)
  292. export AMAP_JS_KEY="用户提供的 JS API Key"
  293. export AMAP_SECURITY="用户提供的安全密钥"
  294. export AMAP_KEY="用户提供的 Web 服务 Key"
  295. # 方式 B:Windows PowerShell
  296. $env:AMAP_JS_KEY="..."
  297. $env:AMAP_SECURITY="..."
  298. $env:AMAP_KEY="..."
  299. # 方式 C:单次命令前置(临时)
  300. AMAP_KEY=xxx AMAP_JS_KEY=yyy AMAP_SECURITY=zzz python inject.py ...
  301. ```
  302. **用户没提供 Key 时**:Skill 应当通过 `AskUserQuestion` 主动询问三类 Key,并指导用户到高德控制台申请;**不要编造或硬编码任何 Key 进 HTML**。
  303. #### 10.3 4 步详细说明
  304. ```bash
  305. SKILL="$SKILL_DIR"
  306. REPORT="$OUTPUT_DIR/{城市}{时间}调查报告_Anysearch版.md"
  307. CITY="{城市}"
  308. # Step 1: agent 抽取地点(你来干,不调脚本)
  309. # 读 $REPORT 全文,按章节识别真实地点:
  310. # - 景点 / 商场 / 餐厅老字号 / 公园 / 地铁站 / 演出场馆 / 喜茶门店 / 美食街
  311. # - 排除:食物名(牛肉丸/砂锅粥)、活动名(夏浪音乐节)、车次号、出口编号、纯描述
  312. # 每个地点写一行 JSON:
  313. # {"name":"广济桥","category":"5A","note":"20元/人,傍晚过河拆桥"}
  314. # 输出到 $REPORT.places.json,schema:
  315. # {"city":"潮州","places":[{"name","category","note"}]}
  316. # Step 2: 服务端地理编码(需要 AMAP_KEY)
  317. python "$SKILL/scripts/geocode.py" \
  318. "$REPORT.places.json" "$CITY"
  319. # 输出: {城市}{时间}调查报告_Anysearch版.places.geo.json
  320. # Step 3: 注入 HTML 模板(需要 AMAP_JS_KEY + AMAP_SECURITY)
  321. # 地图中心自动从地点坐标的修剪中点计算,抗离群值
  322. python "$SKILL/scripts/inject.py" \
  323. "$REPORT.places.geo.json" \
  324. "$OUTPUT_DIR/{城市}地图_Anysearch版.html" \
  325. "$CITY" "{时间范围如 2026/7/4-5}"
  326. # 输出统一命名为 {城市}地图_Anysearch版.html(去掉时间前缀避免重复)
  327. # Step 4: 质量验证
  328. python "$SKILL/scripts/validate_map.py" \
  329. "$OUTPUT_DIR/{城市}地图_Anysearch版.html"
  330. # 检查:文件大小、模板占位符、中心非北京回退、100% 编码、无 NaN、坐标在中国范围
  331. ```
  332. **地点抽取的判断要点(runtime agent 工作清单)**:
  333. 1. **能上地图 = 真实地理坐标**:景点、商场、餐厅、公园、地铁站、演出场馆、酒店等
  334. 2. **不上地图 = 非地点**:食物名(鸭母捻)、活动名(灯光秀)、票价数字、车次号、出口编号、纯形容词
  335. 3. **同名消歧**:开元寺在泉州/潮州/福州都有,按报告上下文选对的那个
  336. 4. **补 known_coords**:`scripts/known_coords.json` 有预置坐标可直接复用,agent 读它做 fast-path
  337. **结果**:双击 `{城市}地图_Anysearch版.html` 即可在浏览器打开,所有标记立即可见。
  338. #### 10.4 11 类配色系统
  339. 地图标记按调查方向分 11 类,采用**水滴形 + 字母**标记,鼠标悬停显示标签:
  340. | 类型 | 字母 | 颜色 | 说明 |
  341. |---|---|---|---|
  342. | 演唱会 | C | 🔴 #d32f2f | 演唱会/音乐会 |
  343. | 球赛 | S | 🟣 #7b1fa2 | 体育赛事 |
  344. | 集市 | M | 🟡 #f9a825 | 集市/夜市 |
  345. | 博物馆 | U | 🔵 #1565c0 | 博物馆/展览 |
  346. | 5A景区 | 5 | 🟠 #e65100 | 5A/4A 景区 |
  347. | 喜茶 | H | 🩷 #ec407a | 喜茶门店 |
  348. | 美食街 | F | 💮 #ad1457 | 美食街/老字号 |
  349. | City Walk | W | 🌊 #00838f | City Walk 路线 |
  350. | 购物中心 | L | 💜 #4527a0 | 商场 |
  351. | 地铁站 | D | ⚪ #546e7a | 地铁关键站 |
  352. | 优惠门票 | T | 🟢 #2e7d32 | 优惠门票 |
  353. #### 10.5 已实现的核心交互
  354. - ✅ **分类筛选 pill**:点击切换显示/隐藏类别
  355. - ✅ **搜索框**:实时过滤卡片(名称/地址/备注)
  356. - ✅ **双向联动**:点击卡片 → 地图飞至 + 打开 InfoWindow;点击标记 → 高亮卡片
  357. - ✅ **自动视野适配**:启动时自动 `setFitView` 包含所有标记
  358. - ✅ **图例**:右下角显示 11 类配色对照
  359. - ✅ **响应式**:手机纵向布局 / 桌面横向布局
  360. - ✅ **NaN 坐标保护**:无坐标的地点不参与地图飞至,提示用户
  361. - ✅ **中心合理性检查**:地图中心为北京但地点在别处时显示警告横幅
  362. #### 10.6 已知问题与修复记录
  363. | 问题 | 根因 | 修复 |
  364. |---|---|---|
  365. | 部分城市中心在北京 | inject.py CENTERS 字典缺失该城市 | 改为从地点坐标**修剪中点**自动计算(抗离群值) |
  366. | 重复文件混乱 | 管线无统一入口,各步骤独立执行 | `build_map.sh` 一键管线,自动清理旧文件 |
  367. | 地图中心偏离 | min/max 中点受离群坐标影响 | 改用**修剪中点**(去除两端 10% 后取中点) |
  368. | HTML 中 TRIP_DATA 无法解析 | JS 对象非 JSON(无引号 key、注释) | validate_map.py 增加 JS→JSON 转换器 |
  369. | **坐标城市错乱**(潮州开元寺→泉州) | known_coords 中"开元寺"存的是泉州坐标;AMAP city 参数只是提示而非硬过滤;geocode.py 不校验返回 city 字段 | ① 删除 known_coords 中多城市共有地名(AMBIGUOUS_NAMES 集);② geocode.py Layer B:校验 AMAP 响应 city 字段,不匹配则重试;③ Layer C:坐标中国范围检查;④ inject.py 防御性过滤(>3° 偏离中心则隐藏) |
  370. #### 10.7 交付
  371. 告知用户:
  372. - Markdown 报告路径
  373. - 地图 HTML 路径(统一为 `{城市}地图_Anysearch版.html`)
  374. - 地点总数 + 编码成功率(100% 预编码)
  375. - 地图验证结果(通过/警告/失败)
  376. ---
  377. ## 调查的 11 个方向
  378. 详细 query 模板见 `references/query_templates.md`。
  379. | # | 方向 | query 数 | 时间过滤方式 | 关键响应字段 |
  380. |---|---|---|---|---|
  381. | 1 | 小红书近期活动 | 1-2 | query 关键词 `近期`/`本周末`/`7月` | `result.content[].text` |
  382. | 2 | 演唱会 | 1 | query 关键词 `7月 最新 排期` | 同上 |
  383. | 3 | 集市 / 市集 | 1 | query 关键词 `近期 市集` | 同上 |
  384. | 4 | 球赛 | 1 | query 关键词 `本周末 球赛` | 同上 |
  385. | 5 | 博物馆 | 1 | 无时间过滤,query 关键词 `2026 推荐` | 同上 |
  386. | 6 | 优惠门票(本地宝) | 1 | query 关键词 `暑期 学生` | 同上 |
  387. | 7 | 喜茶门店 + 购物中心 | 2 | 无时间过滤,query 关键词 `2026 旗舰店` | 同上 |
  388. | 8 | 美食街 | 1 | 无时间过滤 | 同上 |
  389. | 9 | city walk 路线 | 1 | 无时间过滤 | 同上 |
  390. | 10 | 5A 景区 | 1 | 无时间过滤 | 同上 |
  391. | 11 | 地铁路线 | 2 | 无时间过滤 | 同上 |
  392. **总计 11-13 次 API 调用**(anysearch `batch_search` 一次 1-5 并行,3 批次内可完成)。
  393. ---
  394. ## Anysearch API 用法速查
  395. ### 端点(默认走 anysearch CLI,无需直接调 HTTP)
  396. ```bash
  397. # Python 入口(已内置在 SKILL_DIR/scripts/)
  398. python $SKILL_DIR/scripts/anysearch_cli.py
  399. # 常用子命令
  400. python .../anysearch_cli.py search "广州 周末活动" --max_results 10
  401. python .../anysearch_cli.py batch_search --queries '[{"query":"A"},{"query":"B"}]'
  402. python .../anysearch_cli.py get_sub_domains --domain travel
  403. python .../anysearch_cli.py extract --url https://example.com
  404. ```
  405. ### 必选/可选参数
  406. | 参数 | 必选 | 推荐值 |
  407. |---|---|---|
  408. | `query` | ✅ | 中文长尾,4 要素:地点+主题+时效+品类 |
  409. | `max_results` | 可选 | 1-10(默认 10) |
  410. | `domain` / `sub_domain` | 可选 | 垂直域(金融/学术/法律/健康/旅游/...) |
  411. | `sub_domain_params` | 可选 | 垂直域参数(如股票代码) |
  412. ### 响应结构(JSON-RPC 2.0)
  413. ```json
  414. {
  415. "jsonrpc": "2.0",
  416. "id": 1,
  417. "result": {
  418. "content": [
  419. {"type": "text", "text": "--- 标题: ...\nURL: ...\n摘要: ...\n\n--- 标题: ..."}
  420. ]
  421. }
  422. }
  423. ```
  424. ### 字段说明
  425. - 响应是 `result.content[0].text` 纯文本(多结果以 `--- 标题: ...` 分隔)
  426. - 每段包含:标题、URL、摘要三部分
  427. - **无 `summary` AI 摘要**、**无 `datePublished`**、**无 `siteName`**、**无 `thumbnailUrl`**
  428. - 整合报告时按 `--- 标题: ...\nURL: ...\n摘要: ...` 切分
  429. > 完整踩坑与决策树见 `references/anysearch_notes.md`。
  430. ---
  431. ## 关键踩坑(Top 5)
  432. 详细版 + 决策树见 `references/anysearch_notes.md`。
  433. 1. **query 关键词隐式表达时效**:anysearch 无 freshness 参数,靠 `2026年7月`/`近期`/`本周末` 关键词
  434. 2. **不要堆超过 5 个 query 在一个 batch_search**:上限就是 5
  435. 3. **跨城市噪声**:query 强加城市名前缀(`{CITY} {CITY} {主题}`)
  436. 4. **召回数量不是质量指标**:5-7 条高质量文本结果优于 15 条低质量,不要为追求召回量浪费 quota
  437. 5. **anonymous QPS 极低**:建议带 `ANYSEARCH_API_KEY`
  438. ---
  439. ## 报告结构(10 节标准)
  440. 详细模板见 `references/report_template.md`。
  441. ```
  442. 〇、一图速览(表格,11 类标记 + 核心亮点)
  443. 一、下周末 + 月度活动清单(演唱会/集市/球赛/漫展/博物馆/5A)
  444. 二、优惠门票(本地宝 + 5A 景区)
  445. 三、喜茶门店热点(LAB/DP/PINK 等主题店)
  446. 四、美食街
  447. 五、city walk 路线
  448. 六、地铁路线(含 5A 景区 + 商场直达)
  449. 七、周末组合路线(A/B/C 三条主题路线)
  450. 八、时效可靠性说明
  451. 九、API 调用统计
  452. 十、引用源
  453. ```
  454. 每节用 emoji (🏛️ / 🎤 / 🎪 / ⚽ ...) + 表格 + 粗体小标题提升可读性(替代原图片版式)。
  455. ---
  456. ## 跨城市差异预警
  457. 不同城市的 anysearch 索引覆盖存在差异,需要在设计 query 时留余量:
  458. | 维度 | 可能现象 | 应对 |
  459. |---|---|---|
  460. | 冷门城市召回量 | 因城市而异(5-10 条波动) | 接受现状,query 多加区域关键词 |
  461. | 喜茶主题店类型 | 各城市定位不同(LAB/DP/PINK/Cake Lab) | 从 `text` 字段里识别关键词 |
  462. | 地铁出口数据新旧 | 长尾信息文章可能偏旧 | 接受(出口编号基本不变)+ 报告加二次确认提示 |
  463. | 中文旅游垂直域 | 中文旅游域参数 (`domain=travel`) 不一定收录所有城市 | 默认 `general` 域,垂直域作为补充 |
  464. | anonymous QPS | 无 key 时频繁 429 / 慢响应 | 强烈建议带 `ANYSEARCH_API_KEY` |
  465. **核心原则**:**召回数量不是质量指标**,5-7 条高质量文本结果优于 15 条低质量。不要为追求召回量重试浪费 quota。
  466. ---
  467. ## 失败状态码
  468. anysearch 是 JSON-RPC 2.0,主要看 `error.code` + `error.message`:
  469. | 错误 | 原因 | 对策 |
  470. |---|---|---|
  471. | `error.code: -32600` | Invalid Request | 检查 JSON-RPC payload |
  472. | `error.code: -32601` | Method not found | 确认 `tools/call` 参数 |
  473. | `error.code: -32602` | Invalid params | 检查 query / max_results 类型 |
  474. | `error.code: -32603` | Internal error | 重试,或换 query 关键词 |
  475. | `error.code: -32000` (自定义) | Quota exhausted | 配置 `ANYSEARCH_API_KEY` 或等额度恢复 |
  476. | `error.code: -32001` (自定义) | Invalid API key | 换 key |
  477. | HTTP 429 | 频率超限 | `sleep 60` 重试 |
  478. | HTTP 5xx | 服务端异常 | 退避重试 3 次后报错 |
  479. ---
  480. ## 参考文件指引
  481. 何时读哪个 reference:
  482. - **写 query 时** → 读 `references/query_templates.md`(11 个方向的 query body 模板)
  483. - **整合报告时** → 读 `references/report_template.md`(10 节结构 + 表格示例)
  484. - **遇到踩坑时** → 读 `references/anysearch_notes.md`(踩坑 + 决策树 + 状态码表)
  485. - **报告写完后** → 读 `references/quality_check.md`(质量检查 + 补查询迭代,**必做**)
  486. - **用户要 HTML 时** → 用 `scripts/md_to_html.py`(三档优先级转换,内嵌 CSS,响应式)
  487. - **用户要地图时** → 读 `references/map_generation.md`(四步生成 + 模板注入,**Step 10**)
  488. ---
  489. ## 一句话总结
  490. **anysearch CLI + query 关键词时效控制 + 任务间数据复用 + 5+4+2 批次 + 跨城市标准化 SOP + 质量检查迭代 + runtime agent 接管地点抽取 = 11-15 次调用产出 20KB+ 高质量纯文字报告,覆盖 11 个调查方向。**
  491. 记住 7 个关键节点:**先算时间 → 设计 query → 5 路 batch_search 并行 → 按模板整合 → 质量检查迭代**(Step 8 不可跳过)→ **HTML 输出**(Step 9 条件触发)→ **地图面板**(Step 10 条件触发,地点抽取由你 runtime agent 自己干)。
README.md · README · 721 lines

View this file on GitHub (read at the repository's current version: the scan did not record which commit it read)

  1. # Weekend City Trip · 周末城市旅游攻略调研 Skill
  2. > 一个让 AI 帮你 5 分钟深度调研任意中国城市周末玩法的 Claude Code/Codex Skill。
  3. > 基于 **anysearch WebSearch API**(JSON-RPC 2.0),输出图文并茂、可执行的 Markdown / HTML 攻略。
  4. https://weekend-city-trip-agent.liangdabiao.com/
  5. ---
  6. ## 目录
  7. - [这是什么](#这是什么)
  8. - [解决什么问题](#解决什么问题)
  9. - [能调研哪些内容(11 个方向)](#能调研哪些内容11-个方向)
  10. - [使用示例](#使用示例)
  11. - [生成报告长什么样](#生成报告长什么样)
  12. - [前置准备](#前置准备)
  13. - [API Key 配置(必读)](#api-key-配置必读)
  14. - [安装](#安装)
  15. - [工作流程(10 步法)](#工作流程10-步法)
  16. - [项目结构](#项目结构)
  17. - [关键能力](#关键能力)
  18. - [常见问题](#常见问题)
  19. - [限制与边界](#限制与边界)
  20. - [成本估算](#成本估算)
  21. - [贡献](#贡献)
  22. - [许可](#许可)
  23. ---
  24. ## 这是什么
  25. **weekend-city-trip** 是一个 [Claude Code/Codex Skill],专门用来做**中国城市的周末 / 短期(1 个月内)旅游深度调研**。
  26. ### 为什么做这个项目?
  27. 一方面我是积累很多旅游经验,我知道怎样发掘城市的魅力。 例如:小红书近期城市活动 ,演唱会,集市,球赛,博物馆 , 地方宝优惠票 , 有喜茶的购物中心有哪些, 美食街,city walk, 5a景区,以上地点的地铁路线, 全面调查,一个一个完成,然后做成详细文档
  28. 为什么要经常去城市看看?无论是否去过,不是说去过就不去,因为过去去旅游景区那种去不去都一样。关键是看城市化,人的新生活,到处的创新,活动,展会, 兴趣消费,
  29. 从这些,你才知道人们的需求,才知道自己要干嘛,开发什么AI项目,人们需要什么。
  30. 不然,其实我们完全没有创新。多深刻体验我国的城市新兴生活方式!
  31. 我利用我的经验介绍怎样从城市里面发现新东西,有价值的东西,促进自己能够赚钱的方向!
  32. 核心就是:1 要快,skill帮你安排很好的路线,城市最有看点的地方, 2 要准,你直接去到那些新兴活动,市集,生产力丰富,年轻人聚集点,我给你安排好,3 要新,都是最新的城市活动,你去旅游景区全部外地人,没有可能接触到什么真正的城市,我安排的都是本地人聚集的活动地点。
  33. ### 使用示例
  34. 先配置好 API Key (.env), 你只需要对 Claude Code/Codex 说一句话,比如:
  35. > "利用city skill调研下周末广州有什么好玩的"
  36. > "利用city skill调研下个月深圳有什么活动的,并生成地图"
  37. 这个 skill 就会自动:
  38. 1. 算清楚"下周末"是哪两天
  39. 2. 用 **anysearch API** 并行发起 10+ 次中文网页搜索
  40. 3. 把搜索结果按 10 节标准结构整合成一份**图文并茂的 Markdown 报告**
  41. 4. **自动质量检查** — 不达标会触发补查询重写(最多 2 轮迭代)
  42. 5. (可选)把 Markdown 转成**漂亮的 HTML 单文件**方便分享
  43. 6. (可选)把 Markdown 转成**漂亮的 地图 HTML 单文件**方便分享
  44. 最终交付物是一份 20-30 KB 的城市周末行动方案,覆盖吃、喝、玩、乐、行、住各个维度。
  45. ---
  46. ## 解决什么问题
  47. 自己做一份"周末去 XX 城市"的攻略,**手动查资料痛点很明显**:
  48. | 痛点 | 手动方式 | 本 Skill |
  49. |---|---|---|
  50. | **信息分散** | 小红书、大众点评、马蜂窝、本地宝、官方文旅...要查 N 个平台 | 一句话触发,anysearch API 一次性召回主流中文信源 |
  51. | **时效性差** | 翻到的常常是 2022 年的旧攻略 | query 关键词强制带 `2026年7月` / `本周末` / `暑期`,优先近期文章 |
  52. | **缺关键信息** | 演唱会没写票价、地铁没写出口、景区没写优惠 | 11 个方向标准化覆盖,缺啥会自动补查 |
  53. | **结构混乱** | 自己整理笔记东一榔头西一棒槌 | 10 节固定结构,从"一图速览"到"周末组合路线"全覆盖 |
  54. | **可信度低** | AI 一把梭常常幻觉编造 | 强制 ≥ 2 个信源验证 + 显式标注信源 + 出行前二次确认提示 |
  55. | **分享不便** | Markdown 给非技术朋友看不懂 | 一键转 HTML 单文件,自带样式,浏览器打开就能看 |
  56. ---
  57. ## 能调研哪些内容(11 个方向)
  58. | # | 方向 | 典型问题 |
  59. |---|---|---|
  60. | 1 | **小红书近期活动** | 这周小红书上大家都在打卡啥? |
  61. | 2 | **演唱会 / 演出** | 下周末有哪些演唱会?时间场馆票价? |
  62. | 3 | **集市 / 市集** | 哪里有创意市集、古着市集? |
  63. | 4 | **球赛** | 中超 / CBA 主场比赛安排? |
  64. | 5 | **博物馆 / 美术馆** | 必去博物馆有哪些?当前在展什么? |
  65. | 6 | **优惠门票(本地宝)** | 暑期学生特惠、考生免费、半价票? |
  66. | 7 | **喜茶门店 + 购物中心** | 城市 LAB / DP / PINK 主题店在哪?十大购物中心? |
  67. | 8 | **美食街** | 本地人真的会去的美食街是哪几条? |
  68. | 9 | **city walk 路线** | 经典步行路线有哪些?节点 + 拍照点? |
  69. | 10 | **5A 景区** | 城市 5A 景区清单 + 票价 + 交通? |
  70. | 11 | **地铁路线** | 线网总览 + 关键站点出口 + 直达商场? |
  71. **最终整合为 10 节报告**:
  72. ```
  73. 〇、一图速览(表格)
  74. 一、活动全清单(演唱会/集市/球赛/博物馆/5A)
  75. 二、优惠门票
  76. 三、喜茶门店热点
  77. 四、美食街
  78. 五、city walk 路线
  79. 六、地铁路线(含 5A 景区 + 商场直达)
  80. 七、周末组合路线(A/B/C 三条主题路线)
  81. 八、时效可靠性说明
  82. 九、API 调用统计
  83. 十、引用源
  84. ```
  85. ---
  86. ## 使用示例
  87. ### 基础用法(Markdown 输出)
  88. 直接对 Claude Code/Codex 说:
  89. ```
  90. 调研下周末广州有什么好玩的,要图文版
  91. ```
  92. 或者:
  93. ```
  94. 我想本周末去上海,帮我全面调查一下
  95. ```
  96. 或者:
  97. ```
  98. 成都未来一个月旅游调研,情侣向
  99. ```
  100. Claude 会自动触发这个 skill,生成:
  101. ```
  102. D:/fireclaw-travel/广州下周末调查报告_Anysearch版.md
  103. ```
  104. ### 进阶用法(HTML 输出)
  105. 加一句"要 HTML":
  106. ```
  107. 调研下周末杭州,生成 html 报告
  108. ```
  109. 或者用 skill 内部命令:
  110. ```
  111. /weekend-city-trip 杭州,时间下周末,格式 html
  112. ```
  113. 会多生成一份单文件 HTML,自带 CSS,浏览器打开直接看,也方便打印为 PDF 分享给朋友。
  114. ### 进阶用法(地图生成)
  115. 加一句"地图版"/"标在地图上":
  116. ```
  117. 调研下周末杭州,生成地图版
  118. ```
  119. 或:
  120. ```
  121. 调研杭州 7 月 4-5 日,把所有地点标在地图上
  122. ```
  123. 会触发 Step 10 四步流程(agent 抽取地点 → geocode → inject → validate),输出:
  124. - `{城市}{时间}地图_Anysearch版.html`(30-40KB,双击即可打开)
  125. - 11 类水滴形彩色标记 + 分类筛选 + 搜索 + 双向联动
  126. - **不依赖 http 服务器**,坐标预编码,可离线分享
  127. **前提**:用户需自行配置高德 Key(详见 [API Key 配置](#api-key-配置必读))。
  128. ### 明确时间 + 偏好
  129. ```
  130. 调研上海 7 月 4-5 日,带娃亲子向,要 html
  131. ```
  132. skill 会:
  133. - 把时间锁定为 2026/7/4-7/5(具体日期)
  134. - 在 query 里加"亲子 / 家庭 / 儿童"关键词
  135. - 最终生成 MD + HTML 双格式
  136. ---
  137. ## 生成报告长什么样
  138. **典型产出**:
  139. - 文件大小:20-30 KB(MD)/ 30-40 KB(HTML)
  140. - 行数:450-550 行
  141. - 信源数:30-50 个权威网站引用
  142. **信源优先级**:腾讯新闻、网易、人民网、官方文旅局、本地宝、行业垂直媒体(如大麦、猫眼)、小红书高赞笔记。
  143. **报告特点**(anysearch 无 thumbnailUrl,纯文字版):
  144. 1. **一图速览** — 10 秒拿到核心情报表格
  145. 2. **时间地点完整** — 演出有日期、场馆、票价;景点有票价、地铁
  146. 3. **emoji + 表格 + 粗体强调** — 替代图片,信息密度更高
  147. 4. **三条周末路线** — 文艺 / 情侣 / 家庭三种主题,带时间表
  148. 5. **二次确认声明** — 票价 / 演出嘉宾可能变动,标注"出行前请二次确认"
  149. 6. **API 调用透明** — 列出每次调用的 query、返回条数
  150. ---
  151. ## 前置准备
  152. ### 1. anysearch API Key(调研报告必需,可选 anonymous)
  153. 去 [anysearch 官网](https://anysearch.com/console/api-keys) 注册,获取 API Key(格式 `as_sk-xxx`)。
  154. **anonymous 模式也可用**,但 QPS 较低;有 Key 则额度更高。
  155. ### 2. 高德 API Key(地图生成必需,纯调研报告可跳过)
  156. 如果要生成 HTML 地图(Step 10),需要到 [高德开放平台](https://console.amap.com/dev/key/app) 申请**两类 Key**:
  157. - **Web 端(JS API)Key + 安全密钥**:浏览器加载地图底图用
  158. - **Web 服务 Key**:Python 服务端批量地理编码用
  159. **两类是不同的 Key,不能互通**。详细配置见下方 [API Key 配置](#api-key-配置必读) 章节。
  160. ### 3. Python(HTML / 地图输出必需)
  161. - **Python 3.7+**(脚本依赖)
  162. - **推荐安装**(完整 GFM 支持):
  163. ```bash
  164. pip install markdown pymdown-extensions
  165. ```
  166. - **不装也能用**:脚本会自动降级到内置极简转换器,基础表格/代码块/列表都支持
  167. ### 4. Claude Code/Codex
  168. - 已安装 Claude Code/Codex CLI
  169. - 把本 skill 放到 `.claude/skills/weekend-city-trip/`(参见[安装](#安装))
  170. ---
  171. ## 安装
  172. ### 方式 1:克隆到全局 skills 目录
  173. ```bash
  174. 直接命令 claude code/ codex , 帮忙安装skill: github.com/liangdabiao/weekend-city-trip
  175. ```
  176. ### 方式 2:克隆到项目级 skills 目录
  177. ```bash
  178. # 在你的项目目录下
  179. cd your-project/
  180. mkdir -p .claude/skills/
  181. git clone <your-repo-url> .claude/skills/weekend-city-trip
  182. ```
  183. ### 验证安装
  184. 在 Claude Code/Codex 里输入:
  185. ```
  186. /skills
  187. ```
  188. 应该能看到 `weekend-city-trip` 出现在列表里。
  189. ### 验证 API Key 是否生效
  190. ```bash
  191. # 验证 anysearch
  192. echo $ANYSEARCH_API_KEY # 应输出 as_sk-xxx(无 key 也可走 anonymous)
  193. # 验证高德(可选,仅地图生成需要)
  194. echo $AMAP_KEY $AMAP_JS_KEY $AMAP_SECURITY
  195. ```
  196. 更详细的 Key 配置见下方 [API Key 配置](#api-key-配置必读) 章节。
  197. ---
  198. ## API Key 配置(必读)
  199. 本 skill 涉及**两个服务的 API Key**,均需用户自行申请,**skill 不内置任何 Key**。
  200. ### 1. anysearch API Key(调研报告所需,可选 anonymous)
  201. | 项 | 值 |
  202. |---|---|
  203. | 申请地址 | https://anysearch.com/console/api-keys |
  204. | 环境变量 | `ANYSEARCH_API_KEY` |
  205. | 格式 | `as_sk-xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx` |
  206. | 免费额度 | anonymous 也可用(低 QPS),配 Key 升级额度 |
  207. **配置方式**(写入 skill 目录下的 `.env` 也可):
  208. ```bash
  209. # bash / git-bash(推荐持久化到 ~/.bashrc)
  210. export ANYSEARCH_API_KEY="as_sk-xxx"
  211. # Windows PowerShell
  212. $env:ANYSEARCH_API_KEY="as_sk-xxx"
  213. ```
  214. **配额耗尽自动续 Key**:响应 `auto_registered` 字段会自动签发新 Key,agent 会征求用户同意后存盘。
  215. ### 2. 高德 API Key(地图生成必需)
  216. 如果要生成 HTML 地图(Step 10),需要**两类 Key**(不能互通):
  217. | 环境变量 | Key 类型 | 申请入口 | 用途 |
  218. |---|---|---|---|
  219. | `AMAP_JS_KEY` | Web 端(JS API) | 高德控制台 → 应用类型选「Web 端(JS API)」 | 浏览器加载地图底图 |
  220. | `AMAP_SECURITY` | 安全密钥(与 JS API Key 配套) | 同上,Key 详情页可见 | JS API 鉴权(2021-12-02 后申请的 Key 必填) |
  221. | `AMAP_KEY` | Web 服务 | 高德控制台 → 应用类型选「Web 服务」 | Python 服务端批量地理编码 |
  222. **配置方式**:
  223. ```bash
  224. # bash / git-bash(推荐持久化到 ~/.bashrc)
  225. export AMAP_JS_KEY="用户提供的 JS API Key"
  226. export AMAP_SECURITY="用户提供的安全密钥"
  227. export AMAP_KEY="用户提供的 Web 服务 Key"
  228. # Windows PowerShell
  229. $env:AMAP_JS_KEY="..."
  230. $env:AMAP_SECURITY="..."
  231. $env:AMAP_KEY="..."
  232. ```
  233. **两类 Key 不能互通**:
  234. - JS API Key 调 REST 会报 `USERKEY_PLAT_NOMATCH`
  235. - Web 服务 Key 在浏览器加载会被拒绝
  236. **安全密钥的前端暴露**:JS API 安全密钥会出现在最终 HTML 里(高德常规用法,无法避免)。生产环境可通过代理服务器转发隐藏,个人调研直接内置即可。
  237. ### 3. Key 缺失时的行为
  238. | 脚本 | 缺失 Key | 行为 |
  239. |---|---|---|
  240. | Step 5 调研 | `ANYSEARCH_API_KEY` | 自动降级 anonymous(低 QPS) |
  241. | Step 10 `geocode.py` | `AMAP_KEY` | 打印帮助信息 + 退出码 2 |
  242. | Step 10 `inject.py` | `AMAP_JS_KEY` 或 `AMAP_SECURITY` | 打印帮助信息 + 退出码 2 |
  243. 所有错误信息都会指导用户到对应控制台申请,不会编造假 Key。
  244. ---
  245. ## 工作流程(10 步法)
  246. skill 内部执行流程,公开透明,方便排查问题。
  247. ### Step 1:时间锁定
  248. 算清楚"本周末/下周末/未来一个月"对应的具体日期。
  249. **关键洞察**:新闻文章发布时间 ≠ 活动举办时间。一篇 6/26 发布的文章可能在介绍 7/4 的活动,所以 query 必须带 `2026年7月` / `近期` / `本周末` 等时效关键词。
  250. ### Step 2:用户确认
  251. 如果用户消息里已经有城市 + 时间,直接进入 Step 3。否则用 `AskUserQuestion` 询问。
  252. ### Step 3:建任务 + 工作目录
  253. ```
  254. D:/fireclaw-travel/anysearch_{城市拼音}/
  255. ```
  256. 创建 6 个 TodoTask,跟踪进度。
  257. ### Step 4:写 query JSON 文件
  258. 为每个调查方向写 query body。anysearch 无 freshness 字段,改用 query 关键词隐式表达时效。
  259. ```bash
  260. # 通过 anysearch CLI batch_search 调用,详见 references/query_templates.md
  261. ```
  262. ### Step 5:3 路并行批次执行
  263. **anysearch batch_search 1-5 并行**,11 次调用拆成 **5+4+2** 三个批次:
  264. ```bash
  265. python $SKILL_DIR/scripts/anysearch_cli.py batch_search --queries '[
  266. {"query":"广州 周末活动 展览 演出 市集 演唱会 2026年7月","max_results":10},
  267. {"query":"小红书 广州 拍照 网红 打卡 同城活动 暑期","max_results":10},
  268. ...
  269. ]' > "$DIR/r_batch1.json"
  270. ```
  271. ### Step 6:解析响应
  272. anysearch 是 JSON-RPC 2.0,响应在 `result.content[].text`,按 `--- 标题:` 切分多条结果。
  273. **字段**:标题 / URL / 摘要(纯文本 snippet,无 AI 摘要,无 thumbnailUrl)。
  274. ### Step 7:整合纯文字报告(初稿)
  275. 按 10 节标准结构整合,输出到:
  276. ```
  277. D:/fireclaw-travel/{城市}{时间}调查报告_Anysearch版.md
  278. ```
  279. **注意**:这只是初稿,**不等于任务完成**。必须经过 Step 8 质量检查才能交付。
  280. ### Step 8:质量检查与迭代优化(必做)
  281. 这是这个 skill 的**核心差异化能力**,详见 [quality_check.md](references/quality_check.md)。
  282. #### 8.1 自动检查
  283. 用 Python 脚本扫描初稿,5 大维度:
  284. - **完整性**:11 调查方向 + 10 节结构是否齐全
  285. - **准确性**:时间/地点/价格是否真实
  286. - **丰富度**:每节信息密度是否达标
  287. - **可执行性**:周末路线时间是否冲突
  288. - **信源多样性**:关键信息是否 ≥ 2 个信源
  289. #### 8.2 各节最低信息密度
  290. | 章节 | 最低 | 优秀 |
  291. |---|---|---|
  292. | 演唱会/演出 | 3 场 | 5+ 场含时间/场馆/票价 |
  293. | 博物馆 | 3 个 | 5+ 个含当前展览 |
  294. | 5A 景区 | 2 个 | 4+ 个含票价/交通 |
  295. | 优惠门票 | 3 个景区 | 5+ 个含原价/现价/规则 |
  296. | 喜茶门店 | 2 家主题店 | 3+ 家含开业日期/产品 |
  297. | 美食街 | 3 条 | 5+ 条含区域/代表店 |
  298. | city walk | 1 条路线 | 2+ 条含节点/长度 |
  299. | 地铁出口 | 2 个站点 | 4+ 站点含 A/B/C/D 编号 |
  300. #### 8.3 触发补查询(最多 2 轮)
  301. | 触发条件 | 等级 | 行动 |
  302. |---|---|---|
  303. | 任一调查方向完全缺失 | 🔴 必补 | 立刻补查询 |
  304. | 演唱会 < 3 场 | 🔴 必补 | 补查询 |
  305. | 跨城市噪声 > 30% | 🔴 必补 | 重写 query 加强城市前缀 |
  306. | 喜茶门店 < 2 家 | 🟡 建议补 | 补查询 |
  307. | 美食街 < 3 条 | 🟡 建议补 | 补查询 |
  308. | 直达商场 < 5 个 | 🟢 可选 | 视余量决定 |
  309. #### 8.4 迭代控制
  310. - 最多 2 轮补查询(防止无限循环)
  311. - 总 API 调用 ≤ 15 次(初始 11 + 补救 4)
  312. - 第 3 轮仍不达标 → 标注"信息有限"交付
  313. ### Step 9:HTML 输出(可选)
  314. **触发条件**:用户明确要求 HTML 格式。
  315. **前置条件**:Step 8 必须已通过。
  316. ```bash
  317. python .claude/skills/weekend-city-trip/scripts/md_to_html.py \
  318. "D:/fireclaw-travel/{城市}{时间}调查报告_Anysearch版.md"
  319. ```
  320. HTML 特性:
  321. - GFM 完整支持(表格/代码块/引用块)
  322. - 内嵌 CSS(单文件可分享,无外部依赖)
  323. - 中文字体优化(苹方/微软雅黑/思源黑体 fallback)
  324. - 响应式布局(手机/平板/桌面自适应)
  325. - 打印友好(`@media print` 样式,可直接打印为 PDF)
  326. ### Step 10:HTML 地图面板生成(可选)
  327. **触发条件**:用户明确要求生成地图(如"生成地图"、"标在地图上"、"地图版")。
  328. **前置条件**:
  329. - Step 8 已通过
  330. - 用户已配置高德 Key(见 [API Key 配置](#api-key-配置必读))
  331. **四步生成**(agent 抽取 + Python 服务端预编码坐标):
  332. ```bash
  333. SKILL=.claude/skills/weekend-city-trip
  334. REPORT="D:/fireclaw-travel/{城市}{时间}调查报告_Anysearch版.md"
  335. # Step 1: agent 抽取地点(你 runtime agent 读 markdown,识别真实地点,写 places.json)
  336. # → 不调用任何外部 LLM API
  337. # Step 2: 服务端地理编码(需要 AMAP_KEY)
  338. python "$SKILL/scripts/geocode.py" \
  339. "D:/fireclaw-travel/{城市}{时间}调查报告_Anysearch版.places.json" {城市}
  340. # Step 3: 注入模板生成最终 HTML(需要 AMAP_JS_KEY + AMAP_SECURITY)
  341. python "$SKILL/scripts/inject.py" \
  342. "D:/fireclaw-travel/{城市}{时间}调查报告_Anysearch版.places.geo.json" \
  343. "D:/fireclaw-travel/{城市}{时间}地图_Anysearch版.html" \
  344. {城市} "{时间范围如 2026/7/4-5}"
  345. # Step 4: 自动质量验证
  346. python "$SKILL/scripts/validate_map.py" \
  347. "D:/fireclaw-travel/{城市}{时间}地图_Anysearch版.html"
  348. ```
  349. **输出**:双击 `{城市}{时间}地图_Anysearch版.html` 即可打开,**坐标已预编码,无需 http 服务器**。
  350. **地图特性**:
  351. - 11 类水滴形标记(演唱会/球赛/集市/博物馆/5A/喜茶/美食街/City Walk/购物中心/地铁站/优惠门票)
  352. - 分类筛选 pill(显示/隐藏类别)
  353. - 搜索框(实时过滤名称/地址/备注)
  354. - 双向联动(点卡片飞至地图 / 点 marker 高亮卡片)
  355. - 自动视野适配 + 响应式布局
  356. - NaN 坐标保护(无坐标的地点不参与飞至)
  357. **预期效果**:30-70 个地点 → 60-90% 编码成功 → 30-40KB 单文件 HTML。
  358. 详细参考 [`references/map_generation.md`](references/map_generation.md)。
  359. ---
  360. ## 项目结构
  361. ```
  362. weekend-city-trip/
  363. ├── SKILL.md # Skill 主文件(10 步法 + API 用法)
  364. ├── README.md # 本文件
  365. ├── references/
  366. │ ├── query_templates.md # 11 个方向的 query body 模板
  367. │ ├── report_template.md # 10 节报告标准结构模板
  368. │ ├── anysearch_notes.md # anysearch 踩坑清单 + 决策树
  369. │ ├── quality_check.md # 质量检查 + 补查询迭代规则
  370. │ └── map_generation.md # 地图生成工作流(Step 10 详解)
  371. ├── templates/
  372. │ └── map_panel.html # 高德 JS API 2.0 地图模板(占位符)
  373. └── scripts/
  374. ├── md_to_html.py # Markdown → HTML 转换器(Step 9)
  375. ├── geocode.py # places.json → places.geo.json(Step 10-B)
  376. ├── inject.py # geo.json → 最终 HTML(Step 10-C)
  377. ├── validate_map.py # 地图质量验证(Step 10-D)
  378. ├── known_coords.json # 预存坐标库
  379. └── build_map.sh # 一键管线 orchestrator
  380. ```
  381. ### 各文件作用
  382. | 文件 | 何时用 | 内容 |
  383. |---|---|---|
  384. | `SKILL.md` | 主流程入口 | 10 步法、API 用法速查、踩坑 Top 8 |
  385. | `references/query_templates.md` | 设计 query 时 | 11 个方向的 query body 模板,带 {CITY}/{MONTH} 占位符 |
  386. | `references/report_template.md` | 整合报告时 | 10 节结构示例、Python 提取脚本 |
  387. | `references/anysearch_notes.md` | 遇到异常时 | 踩坑详解 + 决策树 + 状态码表 |
  388. | `references/quality_check.md` | 报告写完后 | 5 维度检查 + 12 个触发条件 + 8 个补查询模板 |
  389. | `references/map_generation.md` | 生成地图时 | 四步工作流详解、Key 配置、11 类配色、常见错误排查 |
  390. | `templates/map_panel.html` | 生成地图时 | 高德 JS API 2.0 模板,含 `{{AMAP_JS_KEY}}` / `{{AMAP_SECURITY}}` 占位符 |
  391. | `scripts/md_to_html.py` | 用户要 HTML 报告时 | 三档优先级转换 + 内嵌 CSS |
  392. | `scripts/geocode.py` | 地图 Step 2 | 调高德 Web 服务 REST,补 lat/lng,需要 `AMAP_KEY` |
  393. | `scripts/inject.py` | 地图 Step 3 | 替换模板占位符,输出最终 HTML,需要 `AMAP_JS_KEY` + `AMAP_SECURITY` |
  394. | `scripts/validate_map.py` | 地图 Step 4 | 7 项自动质量检查 |
  395. ---
  396. ## 关键能力
  397. ### 1. 跨城市标准化
  398. 不同城市的搜索召回存在差异。skill 用**城市前缀 + 多区域关键词**应对召回波动。
  399. ### 2. 时效性保障
  400. - query 关键词强制带 `2026年7月` / `本周末` / `暑期`
  401. - 但**理解"发布时间 ≠ 举办时间"**,允许旧文章介绍未来活动
  402. - 报告末尾标注"出行前请二次确认"
  403. ### 3. 信源可信度
  404. - 优先权威媒体(腾讯/网易/人民网/官方文旅)
  405. - 关键信息(票价/演出嘉宾)要求 ≥ 2 个信源验证
  406. - 信源清单完全公开,报告末尾按任务分类列引用
  407. ### 4. 反幻觉
  408. - 不编造未在 snippet 中出现的信息
  409. - 单源可疑数据标注或删除
  410. - runtime agent 全程主导判断与生成(不调任何外部 LLM API)
  411. ### 5. 质量保障闭环
  412. **报告生成 ≠ 任务完成**。Step 8 强制检查 + 最多 2 轮迭代优化,确保交付质量稳定。详见 [quality_check.md](references/quality_check.md)。
  413. ### 6. 失败优雅降级
  414. - markdown 库没装 → markdown2 → 兜底内置转换器
  415. - anysearch 配额耗尽 → 自动续 key(征用户同意后存盘)
  416. - 无 API key → anonymous 模式(低 QPS)
  417. ---
  418. ## 常见问题
  419. ### Q1:一定要 anysearch API 吗?可以用 Google/Bing 吗?
  420. **目前仅支持 anysearch**。原因:
  421. - anysearch 对中文索引覆盖良好
  422. - JSON-RPC 2.0 接口稳定,支持 batch_search 并行
  423. - anonymous 模式可用,配 Key 升级额度
  424. ### Q2:支持海外城市吗?
  425. anysearch 以中文索引为主,海外城市召回偏低。海外场景建议用其他通用 web search skill。
  426. ### Q3:每次调研消耗多少 API 额度?
  427. **11-15 次 query 调用**(初始 11 + 补救 4),按 5+4+2 三批次发起。anonymous 模式 QPS 较低,建议配 Key。
  428. ### Q4:生成的报告可以商用吗?
  429. 报告内容来自公开网页,版权归原作者。**调研结果仅供个人参考**,商用请自行核实版权。
  430. ### Q5:HTML 转换一定要装 markdown 库吗?
  431. **不装也能用**。脚本三档优先级:
  432. 1. python-markdown(完整 GFM)
  433. 2. markdown2(次选)
  434. 3. 内置兜底转换器(基础支持,无需任何外部库)
  435. 但**强烈推荐装** `pip install markdown pymdown-extensions`,完整 GFM 表格、代码高亮、任务列表等特性才完整。
  436. ### Q6:为什么 11 个方向拆成 6 个 TodoTask?
  437. 平衡信息密度与执行效率。同类方向(如演唱会 + 集市 + 球赛)合并到一个任务,既避免任务碎片化,又保持清晰度。
  438. ### Q7:为什么 batch_search 拆 5+4+2 三批?
  439. anysearch `batch_search` 限制 1-5 query 并行。11 个 query 拆 5+4+2 是最经济的批次划分,总耗时 30-60 秒。
  440. ### Q8:报告里有"二次确认"提示,是不是数据不可靠?
  441. **部分信息可能时效性偏弱**(如地铁出口编号、票价微调)。skill 已经做了多源验证,但仍建议:
  442. - 演出票务:出行前到大麦 / 猫眼二次确认
  443. - 景区票价:出行前到官方公众号二次确认
  444. - 营业时间:出行前到大众点评二次确认
  445. ---
  446. ## 限制与边界
  447. ### ✅ 适用场景
  448. - 中国大陆城市调研
  449. - 周末 / 1 个月内短期旅游
  450. - 任意 4-7 线及以上城市(北上广深、成都、杭州、武汉、西安、南京...)
  451. ### ❌ 不适用场景
  452. - 海外城市(召回偏低)
  453. - 长期旅居 / 移民调研(超过 1 个月)
  454. - 单一深度主题(如只查某场演唱会票价 → 直接 WebSearch 即可)
  455. - 极端小众县城(索引可能覆盖不足)
  456. ### 已知限制
  457. - 不同城市召回数量波动 5-15 条
  458. - 长尾信息(地铁出口编号)文章偏旧(2018-2022),但出口编号基本不变
  459. - 无 thumbnailUrl,报告统一纯文字版(emoji + 表格 + 粗体强调)
  460. - 不支持 JS 渲染(复杂 SPA 网页摘要可能不全)
  461. ---
  462. ## 成本估算
  463. ### 时间成本
  464. | 阶段 | 耗时 |
  465. |---|---|
  466. | Step 1-4(准备 + 写 query) | 1-2 分钟 |
  467. | Step 5(并行调用 3 批次) | 30-60 秒 |
  468. | Step 6-7(解析 + 整合) | 3-5 分钟 |
  469. | Step 8(质量检查 + 补查询) | 2-5 分钟(视触发条件) |
  470. | Step 9(HTML 报告输出,可选) | 30 秒 |
  471. | Step 10(HTML 地图生成,可选) | 1-2 分钟(agent 抽取 + geocode + inject + validate) |
  472. | **总计** | **7-15 分钟** |
  473. ### API 额度
  474. **anysearch**(调研报告):
  475. - 初始:11 次 query(5+4+2 三批次)
  476. - 补救:0-4 次(视触发条件)
  477. - **总计:11-15 次**
  478. **高德**(地图生成,可选):
  479. - Web 服务地理编码:30-70 次/城市(每次调研,免费配额 3000 次/日)
  480. - JS API 底图加载:浏览器端调用,免费配额 30 万次/日
  481. - 个人调研完全够用,基本不会触顶
  482. ---
  483. ## 贡献
  484. 欢迎 PR / Issue。特别欢迎以下贡献:
  485. - 新城市的 query 模板优化(不同城市关键词差异)
  486. - 报告结构的本地化适配(如港台场景)
  487. - HTML 模板美化(当前是 GitHub 风格,可加更多主题)
  488. - 翻译为英文(海外华人用户)
  489. ---
  490. ## 许可
  491. MIT License — 详见 [LICENSE](LICENSE)。
  492. ---
  493. ## 一句话总结
  494. **说一句话 → 11-15 次 anysearch API 调用 → 7-15 分钟 → 20-30 KB 纯文字攻略 → 覆盖吃 / 喝 / 玩 / 乐 / 行的 10 节标准报告 + 三条周末路线。**
  495. 让 AI 帮你把"周末去哪玩"的攻略难题,变成一句话的事。
  496. ## 特别感谢:
  497. https://linux.do 社区佬友
  498. https://anysearch.com/ anysearch API 提供方

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.