Kiwi Pin 是一个 Chrome 扩展，帮助在浏览小红书旅游攻略时快速收藏帖子、解析地点并可视化到地图里。本仓库包含完整的前端实现（Manifest V3、React + Vite + Tailwind + Zustand），所有功能均在浏览器本地完成，无后端依赖。
-
小红书帖子收藏
- 在小红书探索页和搜索结果页自动注入收藏按钮
- 一键收藏帖子，保存标题、内容、标签、图片等信息
- 自动下载并缓存帖子图片到本地，避免图片链接过期
-
AI 智能解析地点
- 使用 LLM（大语言模型）自动识别帖子中提到的地点
- 支持文本和图片双重识别（Vision 模式）
- 批量解析多个帖子，提高效率
-
地图可视化
- 使用 Mapbox 地图展示解析出的地点
- 支持 Google Places API 和 Mapbox Geocoding API 进行地点搜索和坐标定位
- 在地图上标记地点，支持导航到 Google Maps
- 支持按文件夹组织地点，方便行程规划
-
数据管理
- 文件夹管理：创建、编辑、删除文件夹，分类管理收藏的帖子
- 数据导入导出：支持 JSON 格式的数据备份和恢复
- 图片缓存管理：查看缓存大小，设置自动清理阈值
- 纯前端实现：所有功能在浏览器本地完成，无需后端服务器
- 隐私安全：数据仅存储在本地浏览器，不会上传到任何服务器
- 离线可用：收藏的帖子和图片缓存在本地，可离线查看
- 现代化技术栈：React 19 + TypeScript + Vite + Tailwind CSS + Zustand
cd ~/kiwi-pin/kiwi-extension
npm installManifest V3 扩展无法直接使用浏览器 Dev Server，需要持续编译打包后再在 Chrome 中加载 dist 目录。
# 持续监听构建（极推荐开发时使用）
npm run dev该命令会以 development 模式执行 vite build --watch，增量产出到 dist/。每次保存代码后，dist 会更新，刷新扩展即可看到最新效果。
npm run builddist/ 将包含发布所需的所有文件，可直接打包上传或在 Chrome 中以“加载已解压的扩展程序”形式载入。
- 打包或监听构建后，打开
chrome://extensions - 开启右上角“开发者模式”
- 点击“加载已解压的扩展程序”，选择
kiwi-extension/dist目录 - 针对不同模块的调试方式：
- Content Script：在小红书页面（
https://www.xiaohongshu.com/explore）打开 DevTools → Sources → Content scripts，即可看到content/index.js - Background Service Worker：在扩展管理页点击“service worker”，弹出新 DevTools 窗口，可查看日志
- Dashboard / Options / Popup 页面：直接在扩展页面中右键“检查”，即可使用常规 DevTools
- Content Script：在小红书页面（
- 如需更新代码：
- 运行
npm run dev保持 watch - 在扩展管理页点击“重新加载”按钮（或开启
auto reload extensions插件自动刷新） - 刷新目标页面（例如小红书）以确保最新脚本生效
- 运行
在使用 Kiwi Pin 之前，需要配置以下 API Key 和 Token。进入扩展的配置页（右键扩展图标 → "选项"，或在扩展管理页点击"详细信息" → "扩展选项"）进行设置。
用于 AI 解析帖子中的地点信息。
支持的 LLM 服务：
- OpenAI（默认）：
https://api.openai.com/v1 - 其他兼容 OpenAI API 格式的服务（如 Azure OpenAI、其他代理服务等）
配置步骤：
- 获取 API Key：
- OpenAI：访问 OpenAI Platform 创建 API Key
- 其他服务：根据服务提供商获取相应的 API Key
- 在配置页填写：
- API Base URL：API 服务的基础地址（默认：
https://api.openai.com/v1） - API Key：你的 API Key
- 模型：使用的模型名称（默认：
gpt-4o-mini） - 启用 Vision：是否启用图片识别功能（推荐开启）
- API Base URL：API 服务的基础地址（默认：
推荐配置：
- 模型：
gpt-4o-mini（性价比高）或gpt-4o（准确度更高） - 启用 Vision：开启（可识别图片中的地点信息）
- Temperature：0.2（较低的值保证输出稳定性）
- 超时时间：30000ms（30秒）
用于地图显示和地点搜索。
配置步骤：
- 访问 Mapbox 注册账号
- 登录后进入 Account → Tokens
- 创建或复制你的 Access Token（默认 token 即可使用）
- 在配置页填写 Mapbox Access Token
注意事项：
- Mapbox 提供免费额度（每月 50,000 次地图加载）
- 超出免费额度后需要付费，但个人使用通常不会超出
用于地点搜索和坐标定位。
配置步骤：
- 访问 Google Cloud Console
- 创建新项目或选择现有项目
- 启用 Places API：
- 进入"API 和服务" → "库"
- 搜索"Places API"
- 点击"启用"
- 创建 API Key：
- 进入"API 和服务" → "凭据"
- 点击"创建凭据" → "API 密钥"
- 复制生成的 API Key
- （可选）限制 API Key 使用范围：
- 点击创建的 API Key 进行编辑
- 在"API 限制"中选择"限制密钥"
- 仅勾选"Places API"
- 在"网站限制"中添加
chrome-extension://*（用于扩展）
- 在配置页填写 Google Places API Key
注意事项：
- Google Places API 有免费额度（每月 $200 免费额度，约 28,000 次请求）
- 超出免费额度后按使用量付费
- 建议设置 API Key 使用限制，避免意外费用
- 默认中心点：地图初始显示的中心坐标（默认：北京
39.9042, 116.4074） - 默认缩放级别：地图初始缩放级别（默认：5）
- 自动清理阈值：当缓存大小超过此值时自动清理（默认：512 MB）
- 可在配置页查看当前缓存大小，手动清理缓存
配置完成后，在收藏页面（Dashboard）会显示配置状态：
- ✅ 绿色：配置完整
⚠️ 黄色：缺少部分配置- ❌ 红色：缺少必需配置
所有必需配置（LLM API Key、Mapbox Token、Google Places API Key）都配置完成后，才能正常使用所有功能。
-
收藏帖子
- 访问小红书探索页（
https://www.xiaohongshu.com/explore）或搜索结果页 - 点击页面右下角的 Kiwi Pin 浮动按钮，启用收藏功能
- 帖子右上角会出现 ➕ 按钮，点击即可收藏
- 收藏的帖子会自动保存标题、内容、标签、图片等信息
- 访问小红书探索页（
-
解析地点
- 打开收藏页面（点击浮动按钮菜单中的"进入收藏页面"）
- 在帖子列表中选择要解析的帖子
- 点击"批量解析"按钮，系统会使用 LLM 自动识别帖子中的地点
- 解析完成后，系统会使用 Google Places 和 Mapbox 搜索地点的坐标
-
查看地图
- 在收藏页面右侧地图上可以看到解析出的地点标记
- 点击地点标记可以查看详细信息
- 点击导航按钮可以跳转到 Google Maps 进行导航
-
管理文件夹
- 创建文件夹来分类管理收藏的帖子
- 将帖子移动到不同文件夹，方便行程规划
- 在地图上可以按文件夹筛选显示地点
- 数据备份：在配置页可以导出所有收藏数据为 JSON 文件，也可以导入之前备份的数据
- 图片缓存：帖子图片会自动下载到本地，即使原链接过期也能正常查看
- 批量操作：支持批量解析、批量删除等操作，提高效率
- Content Script 内已加入 toast 与日志，可快速验证收藏逻辑
- Dashboard 页在地图上展示解析出的 Marker，支持导出行程数据
- Options 页可直接触发缓存清理、查看缓存大小，便于验证图片下载逻辑
- 若遇到权限或 API 调用失败，可在 background Service Worker 的 console 查看详细报错
- 接入更多地图能力（如路线规划）
- 增加收藏数据的离线备份与导入校验提示
- 进一步完善单元测试与 E2E 测试（当前仅保留基础脚手架）