门店拜访洞察工具

任务目标

本 Skill 用于: 将门店拜访录音自动化处理为结构化洞察数据，生成本地知识库和统计看板
能力包含: 音频转写、结构化提取、报告生成(Markdown/Word)、SQLite本地知识库、统计看板
触发条件: 用户上传拜访录音、要求分析拜访数据、生成拜访报告、查看拜访统计

前置准备

ASR语音转写服务（用户自行注册）

本技能的语音转写功能由火山引擎提供，费用由火山引擎直接向用户收取，与本技能开发者无关。

注册步骤（5分钟完成）：

访问 https://console.volcengine.com/speech/new/setting/apikeys 登录火山引擎新版控制台
完成实名认证（如未完成）
点击"创建API Key"获取密钥

凭证配置格式：

{"api_key":"你的APIKey"}

费用说明： | 阶段 | 额度 | 费用 | |------|------|------| | 免费试用 | 20小时（半年有效） | 0元 | | 资源包 | 30小时 | 23元 | | 大规格包 | 1000小时 | 750元（0.75元/小时） |

20小时免费额度约可处理40次拜访（每次30分钟），足够验证产品价值。

购买入口： 控制台 → 开通管理 → 录音文件识别 → 购买资源包

其他依赖

依赖说明: 脚本依赖 python-docx(Word文档生成)，首次运行会自动安装
系统依赖: ffmpeg(音频格式转换)，需用户手动安装并加入 PATH
凭证配置: 需配置环境变量 VOLCENGINE_ASR_API_KEY，值为包含 api_key 的 JSON（见上方格式）
数据隐私: 所有拜访数据存储在用户本地SQLite文件中，Skill不持有或上传任何用户数据

操作步骤

首次使用：初始化

确认用户行业，选择对应模板
- 读取 references/industry-templates.md 获取行业模板定义
- 询问用户所属行业：快消零售/连锁餐饮/医药OTC/母婴用品/美妆个护/通用
- 记录行业选择，后续提取和报告均使用对应模板

初始化本地数据库

python scripts/db_manager.py --db ./visit_data.db --action init

核心流程：处理单次拜访

步骤1：音频转换（可选）

火山引擎ASR直接支持wav/mp3/m4a/ogg格式。仅当音频为amr等特殊格式时需转换。

python scripts/audio_convert.py --input <音频文件路径> --output <输出WAV路径>

支持格式: mp3/m4a/wav/amr/aac/flac/ogg/3gp
输出: 16kHz/16bit/单声道 PCM WAV
文件大小限制: 200MB
仅验证不转换: 加 --validate-only 参数

步骤2：语音转写

调用火山引擎ASR将音频转写为文字。支持wav/mp3/m4a/ogg格式，无需预先转换。

python scripts/asr_transcribe.py --input <WAV文件路径>

输出: JSON格式，包含full_text(完整文本)和segments(分段文本)
凭证从环境变量 VOLCENGINE_ASR_API_KEY 自动读取，无需手动传入

步骤3：结构化信息提取（智能体处理）

此步骤由智能体完成，不需要调用脚本。

读取 references/field-definitions.md 获取字段定义和提取规则
根据用户选择的行业模板，使用对应的提取提示词
从转写文本中提取结构化字段:
- 门店名称、拜访人、拜访日期（无法提取时要求用户补充）
- 拜访目的、店主反馈、竞品动态
- 机会点、问题与风险、待办事项
对置信度低于80%的字段高亮标记，提示用户确认
用户确认后，生成完整的结构化JSON记录

步骤4：数据入库

将结构化记录保存到本地SQLite数据库。

python scripts/db_manager.py --db ./visit_data.db --action insert --data '<JSON格式的记录>'

--data参数接收完整的拜访记录JSON字符串
记录自动关联门店名称、日期、区域等索引字段

步骤5：生成报告

根据用户需求生成分析报告。

Markdown报告: 由智能体直接生成，包含以下结构:

拜访概况（基本信息、拜访目的）
关键洞察（店主反馈、竞品动态、机会点、问题风险）
行动建议（待办事项、优先级排序）

Word报告: 调用脚本将Markdown或JSON转为Word文档。

python scripts/generate_docx.py --input <Markdown文件路径> --output <输出docx路径> --title "报告标题"

知识检索

用户查询历史拜访数据时:

# 按条件查询
python scripts/db_manager.py --db ./visit_data.db --action query --store-name "门店名" --start-date "2024-01-01" --end-date "2024-12-31"

# 全文检索
python scripts/db_manager.py --db ./visit_data.db --action search --keyword "关键词"

统计看板

生成拜访统计数据:

# JSON格式输出
python scripts/statistics.py --db ./visit_data.db --start-date "2024-01-01" --end-date "2024-12-31"

# Markdown格式看板
python scripts/statistics.py --db ./visit_data.db --output-format markdown --output ./dashboard.md

看板包含: 核心指标(拜访总数/门店数/时长)、区域分布、拜访人排名、TOP问题、每日趋势。

批量处理

用户上传多个录音时的处理流程:

逐个执行步骤1-2（音频转换+转写）
转写完成后，尝试从每段对话中自动提取门店名称
批量展示提取结果，让用户确认/修正门店关联
支持统一标注（"这批都是XX门店的"）或逐个标注
确认后批量入库

数据导出

# 导出为JSON
python scripts/db_manager.py --db ./visit_data.db --action export --output ./export.json --format json

# 导出为CSV
python scripts/db_manager.py --db ./visit_data.db --action export --output ./export.csv --format csv

使用示例

示例1：单次拜访录音处理

场景: 业务员完成门店拜访后上传录音
输入: "帮我整理一下这次拜访的录音" + 上传mp3文件
处理流程: 音频转换 → 转写 → 结构化提取 → 入库 → 生成报告
预期产出: 结构化拜访记录卡片 + Markdown分析报告
关键要点: 首次使用需确认行业模板；AI自动提取门店名，提取不到时询问用户

示例2：历史数据检索

场景: 用户想查找某门店的历史拜访记录
输入: "查一下XX便利店上个月的所有拜访记录"
处理流程: 调用db_manager查询 → 格式化展示结果
预期产出: 按时间排列的拜访记录列表，含摘要信息
关键要点: 支持模糊匹配门店名，支持时间范围筛选

示例3：统计看板生成

场景: 区域经理查看本月团队拜访情况
输入: "生成本月的拜访统计看板"
处理流程: 调用statistics.py → 生成Markdown看板
预期产出: 包含核心指标、区域分布、拜访人排名、TOP问题、日趋势的看板
关键要点: 默认统计最近30天数据，支持按区域/行业筛选

资源索引

脚本: 见 scripts/audio_convert.py(用途: 音频格式转换，将m4a/mp3/amr等转为PCM WAV)
脚本: 见 scripts/asr_transcribe.py(用途: 火山引擎ASR语音转写，需配置 VOLCENGINE_ASR_API_KEY 环境变量)
脚本: 见 scripts/db_manager.py(用途: SQLite数据库管理，支持init/insert/query/search/stats/delete/export)
脚本: 见 scripts/generate_docx.py(用途: 将Markdown/JSON转为Word文档)
脚本: 见 scripts/statistics.py(用途: 生成拜访统计看板数据)
参考: 见 references/industry-templates.md(何时读取: 首次使用时选择行业模板，或需要行业专属字段定义时)
参考: 见 references/field-definitions.md(何时读取: 执行结构化信息提取时，获取字段定义和AI提取提示词)

注意事项

数据完全存储在用户本地，Skill不上传或持有用户数据，这是核心隐私承诺
火山引擎ASR按量计费(约0.75元/小时)，注意提醒用户关注用量和费用
音频转换依赖ffmpeg，请先手动安装并加入 PATH（Windows: winget install ffmpeg；macOS: brew install ffmpeg；Linux: sudo apt-get install ffmpeg），未安装时会报错提示
结构化提取由智能体完成，提取质量取决于转写文本的准确度和行业模板的匹配度
批量处理时注意控制并发，避免火山引擎API限流
报告中的Word格式依赖python-docx库，首次运行会自动安装