xuanzhi-zhuanjia — 选址投资调研技能

百度地图POI检索 + Agent Reach多平台交叉验证 + 报告生成，一站式选址投资分析工具。

核心能力

1. 百度地图POI检索：以目标地址为中心，批量检索周边各类POI（充电站、住宅小区、餐饮、停车场、酒店、学校、医院等），获取名称、地址、距离、电话等结构化数据
2. Agent Reach多平台交叉验证：通过小红书（用户口碑）、B站（行业内容）、Exa AI搜索（政策招标）三个平台并行获取真实用户反馈和宏观数据
3. 报告生成：整合POI数据和多平台调研结果，生成包含竞品分析、人流分析、财务测算、SWOT分析、投资建议的完整选址投资报告（Markdown + Word双版本）

前置依赖

1. Python 环境

需要 Python 3.8+。POI检索脚本仅使用标准库，无需额外安装。报告生成需要 python-docx。

# 创建 venv 并安装 python-docx（仅需一次）
python3 -m venv ~/.xuanzhi-venv
~/.xuanzhi-venv/bin/pip install python-docx      # macOS/Linux
# 或 Windows:
# ~/.xuanzhi-venv/Scripts/pip.exe install python-docx

> WorkBuddy 环境：使用 managed Python：
> - Python: C:/Users/leoqing/.workbuddy/binaries/python/versions/3.13.12/python.exe
> - venv: C:/Users/leoqing/.workbuddy/binaries/python/envs/default/Scripts/python.exe

2. 百度地图开发者 AK（必需，每位用户自备）

> ⚠️ 本技能【不含任何内置 AK / 私钥】。 POI 检索依赖百度地图 Web API，
> 每位使用者必须使用【自己申请】的服务端 AK。切勿把 AK 写死在代码里随包分发。

AK 自助申请流程（引导用户完成，作为使用本技能的第 1 步）：

1. 打开 https://lbsyun.baidu.com/ 注册账号并完成实名认证（个人/企业均可，免费）。
2. 进入「控制台 → 应用管理 → 我的应用 → 创建应用」。
3. 应用类型选择「服务端」（POI 检索走服务端 API）；应用名称自取，IP 白名单本地使用可填 0.0.0.0/0 或暂时留空。
4. 创建后复制生成的 AK（一串 32 位字符）。
5. 把 AK 通过环境变量告诉本技能（不要硬编码进脚本）：

# macOS / Linux / Windows(Git Bash)
export BAIDU_MAP_AK=你复制的AK

# Windows (PowerShell)
$env:BAIDU_MAP_AK="你复制的AK"

# 更安全：把 AK 写入仅自己可读的文件，再指向它（避免 AK 出现在命令行历史）
#   Windows(PowerShell):  $env:BAIDU_MAP_AK_FILE="C:/path/to/baidu_ak.txt"
#   macOS/Linux:          export BAIDU_MAP_AK_FILE=/path/to/baidu_ak.txt

> 安全提醒：明文 BAIDU_MAP_AK 会出现在命令行历史/进程环境中。更稳妥的做法是把 AK 存入文件并用 BAIDU_MAP_AK_FILE 指向它；该文件切勿提交到 git 或分享给他人。

启动校验：设置好 AK 后启动 POI 服务（见下方 Step 1）。若未设置 AK，脚本会直接拒绝启动并打印申请引导，不会回退到任何默认密钥。

3. Agent Reach（多平台调研依赖）

Agent Reach 是一个开源的互联网能力路由器，为 AI Agent 提供小红书、B站、Exa搜索等15个平台的访问能力。

核心能力：
- 15个平台、多后端路由（OpenCLI / 平台专属CLI / API）
- 6个渠道零配置即可使用（Exa搜索、GitHub、网页阅读、V2EX、B站、YouTube字幕）
- 多后端平台先跑 agent-reach doctor --json 体检，按 active_backend 选命令

完整安装和使用说明：见 references/agent_reach_skill.md

快速安装（5步）：

# Step 1: 创建独立 venv
python3 -m venv ~/.agent-reach-venv

# Step 2: 安装 agent-reach 包
~/.agent-reach-venv/bin/pip install "https://github.com/Panniantong/agent-reach/archive/main.zip"

# Step 3: 运行安装器（自动检测环境并安装核心工具）
~/.agent-reach-venv/bin/agent-reach install --env=auto

# Step 4: 配置 Exa 搜索（如安装器未自动配置）
mcporter config add exa https://mcp.exa.ai/mcp

# Step 5: 体检确认
~/.agent-reach-venv/bin/agent-reach doctor --json

> Windows 用户将 ~/.agent-reach-venv/bin/ 替换为 ~/.agent-reach-venv/Scripts/

安装后验证：确保以下三个渠道可用（xuanzhi-zhuanjia 核心依赖）：
- 小红书：opencli xiaohongshu search "测试" -f yaml（需 Chrome 登录过小红书）
- B站：bili search "测试" --type video -n 3 --yaml（零配置，无需登录）
- Exa：mcporter call 'exa.web_search_exa(query: "测试", numResults: 1)'（零配置）

> 如果 Agent Reach 未安装：xuanzhi-zhuanjia 仍可运行 POI 检索和报告生成，但会跳过多平台交叉验证步骤。应在开始前告知用户：「Agent Reach 未安装，将跳过多平台交叉验证。如需完整调研能力，请按 references/agent_reach_skill.md 安装 Agent Reach。」

标准工作流程

Step 1：引导用户配置 AK 并启动 POI 检索服务

> 首步前置（强制）：在启动任何检索前，必须先确认用户已自备百度地图 AK。
> 若用户尚未申请，先按上方「百度地图开发者 AK」引导其完成注册 → 创建服务端应用 → 获取 AK，
> 并协助其通过环境变量 BAIDU_MAP_AK（或 BAIDU_MAP_AK_FILE）配置好。
> AK 就绪前，不得进入 Step 2 的检索。

1.1 检查 AK 是否已配置

# Windows (PowerShell) 检查
echo $env:BAIDU_MAP_AK
# macOS/Linux/Git Bash 检查
echo $BAIDU_MAP_AK

• 若已返回 AK 值 → 直接进入 1.2 启动服务。
• 若为空 → 不要启动；先完成 AK 引导（上方「百度地图开发者 AK」），配置后再继续。

1.2 启动 POI 服务

# 启动（后台运行）
python3 scripts/poi_search_template.py
# 服务运行在 http://127.0.0.1:8000/

> 脚本路径（相对于技能目录）：scripts/poi_search_template.py

1.3 验证服务健康

curl -s http://127.0.0.1:8000/health
# 应返回 {"status": "ok"}

Step 2：地理编码 + POI 批量检索

2.1 地理编码目标地址

# 传入地址名，自动地理编码获取坐标
curl -s "http://127.0.0.1:8000/api/poi-search?location=目标地址名&query=锚点关键词&radius=500"

从返回结果的 meta.center 获取坐标（lat,lng）。

2.2 批量检索周边POI

用获取的坐标，按场景批量检索各类POI：

接口用法（同一个接口三种模式）：
- 地址+半径（自动地理编码）：/api/poi-search?location=XX地址&query=关键词&radius=3000
- 坐标+半径（更快）：/api/poi-search?location=lat,lng&query=关键词&radius=3000&page_size=20
- 城市内搜索：/api/poi-search?city=成都市&query=充电站

> 建议写一个批量检索脚本（Python），一次拉取所有类别 POI 并保存为 JSON，避免逐条手动调用。

Step 3：Agent Reach 多平台交叉验证

声明：使用 agent-reach 的 Exa 搜索 + 小红书（OpenCLI后端）+ B站（bili-cli后端）。

3.1 先体检（首次使用或遇到问题时）

agent-reach doctor --json

按各平台的 active_backend 选择命令组。

3.2 三平台并行搜索

# Exa AI搜索：政策/招标/行业数据/房价
mcporter call 'exa.web_search_exa(query: "目标城市 关键词 政策 投资", numResults: 5)'

# 小红书：用户口碑/真实评价/倒闭案例
opencli xiaohongshu search "目标城市 关键词" -f yaml

# B站：行业视频/投资教程/选址方法论
bili search "关键词 投资 选址" --type video -n 5 --yaml

3.3 深挖关键信息

• 小红书：对高互动笔记用 opencli xiaohongshu note "NOTE_URL" -f yaml 读正文
• Exa：对重要网页用 curl -s "https://r.jina.ai/URL" 读全文
• B站：对高播放视频用 bili video BVxxx 获取详情

> 详细的命令用法、重试链、注意事项见 references/agent_reach_skill.md

Step 4：数据整合分析

• POI数据：按距离排序、按品牌归类、统计各半径内数量分布
• 小红书：提炼用户痛点、口碑评价、风险信号（如倒闭案例）
• Exa：补充政策补贴、招标信息、行业盈利数据
• B站：参考行业选址方法论和成本利润测算
• 形成分析结论和经营/投资建议

Step 5：生成报告

输出 Markdown 和 Word 双版本到当前工作目录。

报告标准结构（可根据场景调整）：
1. 执行摘要（核心结论）
2. 项目概况（目标地址、坐标、锚点门店）
3. 区位与交通分析
4. 周边人流与配套分析（住宅/酒店/学校/医院等）
5. 竞品分析（重点，含完整竞品列表和距离分布）
6. 多平台交叉验证（Exa/小红书/B站各自发现）
7. 财务测算（投资成本/收入测算/补贴/回收期）
8. SWOT分析
9. 投资建议（总体结论+差异化方向+替代选址）
10. 数据附录（完整POI列表）

Word 报告生成：

# 使用 venv 中的 python 运行报告生成脚本
# macOS/Linux: ~/.xuanzhi-venv/bin/python report_script.py
# Windows: ~/.xuanzhi-venv/Scripts/python.exe report_script.py

停止服务

# 查找并停止 POI 服务进程
# macOS/Linux
pkill -f poi_search_template.py

# Windows (PowerShell)
Get-Process -Name python* | Where-Object { $_.CommandLine -like '*poi_search_template*' } | Stop-Process

可移植性说明（迁移到其他电脑/平台）

1. 复制 xuanzhi-zhuanjia/ 整个目录到目标 agent 平台的 skills 目录
2. 确保安装 Python 3.8+，创建 venv 并安装 python-docx
3. 配置百度地图 AK（环境变量 BAIDU_MAP_AK 或 BAIDU_MAP_AK_FILE，每位用户自备，详见上方「百度地图开发者 AK」）
4. 按 references/agent_reach_skill.md 安装 Agent Reach
5. 启动 POI 服务，开始使用

文件结构：

xuanzhi-zhuanjia/
├── SKILL.md                              # 本文件，主技能定义
├── scripts/
│   └── poi_search_template.py            # 百度地图POI检索HTTP服务
└── references/
    └── agent_reach_skill.md              # Agent Reach完整skill（安装+使用说明）

注意事项

• POI 检索服务监听 0.0.0.0:8000，如端口冲突需修改脚本
• 百度地图 API 有配额限制，批量检索时建议间隔 0.3-0.5 秒
• 小红书高频请求会触发验证码，每次操作间隔 2-3 秒
• 临时文件（批量检索结果、中间数据）放在系统临时目录（/tmp/ 或 %TEMP%），不要污染工作区
• 最终报告输出到当前工作目录