门店拜访洞察工具

任务目标

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

前置准备

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

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

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

凭证配置格式：

{"api_key":"你的APIKey"}

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

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

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

其他依赖

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

操作步骤

首次使用：初始化

0. 运行环境检查（建议先做）
   bash python scripts/check_env.py
   - 一键检测 ffmpeg / python-docx / requests / API Key 是否就绪
   - API Key 缺失仅影响路径 A；若只用路径 B（粘贴文本）可忽略该提示

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

2. 初始化本地数据库
   bash python scripts/db_manager.py --db ./visit_data.db --action init

核心流程：处理单次拜访

本技能提供两条入口，完成"音频→文字"这步后，后续流程完全一致：

• 路径 A（推荐，需联网）：上传录音 → 步骤1音频转换 → 步骤2火山引擎ASR转写 → 步骤3
• 路径 B（零门槛，无需凭证）：直接粘贴/上传转写文本 → 跳过步骤1-2 → 直接进入步骤3

> 路径 B 适合：没有火山引擎 API Key、网络受限、或已用其他工具得到文字稿的用户。核心的"结构化提取→入库→报告"能力完全一致。

路径 B：手动粘贴转写文本（无需 ASR 凭证）

用户粘贴对话文字稿（或上传 .txt/.md 文件）后：

# 方式1：直接粘贴文本
python scripts/transcription_from_text.py --text "粘贴的对话文字稿..."

# 方式2：从文本文件读取
python scripts/transcription_from_text.py --input ./transcription.txt --output ./transcription.json

• 输出标准 JSON（text + segments），与路径 A 的 ASR 输出格式兼容
• 随后直接进入 步骤3：结构化信息提取，无需执行步骤1-2

步骤1：音频转换（可选，仅路径 A）

火山引擎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：结构化信息提取（智能体处理）

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

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

步骤3.5：数据后处理校验（入库前必做）

在入库前，对结构化记录做以下校验（可调用 scripts/validate_record.py 辅助，也可由智能体直接检查）：

• 必填字段非空：store_name、visit_date、visitor、visit_purpose 不得为空；缺失时主动提示用户补充。
• 门店名历史查重：用 db_manager.py --action query --store-name "<门店名>" 比对历史记录，若已存在同名/高度相似门店，提示用户确认是否为同一家（避免重复建店）。
• 日期合法性：visit_date 不早于 1 年前、不晚于明天；action_items.deadline 不早于 visit_date。异常时告警。
• 枚举值合规：store_type、overall_sentiment、cooperation_willingness、priority/urgency、status 等须落在 field-definitions.md 规定的值域内。
• 关键字段缺失告警：owner_feedback / opportunities / issues / action_items 任一为空时，提示"本次拜访是否确实无相关内容"。

# 示例：校验一条待入库记录
python scripts/validate_record.py --data '<JSON格式的记录>' --db ./visit_data.db
# 返回 {"valid": true/false, "errors": [...], "warnings": [...]}

校验通过后再进入步骤4 入库。

步骤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

# HTML可视化看板（单文件离线，内联SVG图表，无需联网）
python scripts/statistics.py --db ./visit_data.db --output-format html --output ./dashboard.html
# 或直接调用：
python scripts/dashboard_html.py --db ./visit_data.db --output ./dashboard.html

看板包含: 核心指标、店主整体情绪、区域分布、拜访人排名、TOP问题类型、问题详情（严重度+门店+具体描述）、机会点、待办事项、每日趋势。HTML 看板提供柱状图/折线图可视化，双击即可在浏览器离线查看，适合向区域经理/老板汇报。

批量处理

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

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

多用户与团队协作（v1.2.0 新增）

本技能支持多业务员数据汇总与基于角色的权限管理（RBAC），且数据仍完全本地化。

角色与范围
- 管理员(admin)：全部数据 + 用户管理
- 区域经理(manager)：所辖 team_id（或同 region）全部成员数据
- 业务员(salesperson)：仅本人数据

启用方式：在 db/统计/导出等命令上加 --as-user <用户ID> 即可按角色隔离数据并校验权限；不传则向后兼容单用户模式（视为管理员）。

# 1) 初始化（自动建 users 表；旧库自动补 owner_id 列）
python scripts/db_manager.py --db ./team.db --action init

# 2) 管理员注册团队成员
python scripts/db_manager.py --db ./team.db --action register_user --as-user admin01 \
  --user-id admin01 --name 王总 --role admin
python scripts/db_manager.py --db ./team.db --action register_user --as-user admin01 \
  --user-id mgr01 --name 李经理 --role manager --team-id east --uregion 华东
python scripts/db_manager.py --db ./team.db --action register_user --as-user admin01 \
  --user-id s01 --name 张业务员 --role salesperson --team-id east --uregion 华东

# 3) 业务员提交记录（owner_id 自动取本人；越权提交会被拒绝）
python scripts/db_manager.py --db ./team.db --action insert --as-user s01 --data '<JSON>'

# 4) 经理查看团队看板（自动含"团队成员对比"与范围隔离）
python scripts/statistics.py --db ./team.db --as-user mgr01 --output-format html --output ./team.html

# 5) 业务员只能看自己
python scripts/statistics.py --db ./team.db --as-user s01 --output-format markdown

权限矩阵、数据归属与汇总口径等详见 references/collaboration.md。

数据导出

# 导出为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/transcription_from_text.py(用途: 手动粘贴/上传文本转为标准转写JSON，无需ASR凭证，对应路径B)
• 脚本: 见 scripts/check_env.py(用途: 首次使用前一键检测 ffmpeg/python-docx/requests/API Key 是否就绪)
• 脚本: 见 scripts/validate_record.py(用途: 入库前校验记录——必填/枚举/日期/门店名查重，返回 errors 与 warnings)
• 脚本: 见 scripts/db_manager.py(用途: SQLite数据库管理，支持 init/insert/query/search/stats/delete/export，以及用户管理 register_user/list_users/set_role/team_members，所有读/写/删操作支持 --as-user 范围隔离与权限校验)
• 脚本: 见 scripts/generate_docx.py(用途: 将Markdown/JSON转为Word文档)
• 脚本: 见 scripts/statistics.py(用途: 生成拜访统计看板数据，支持 json/markdown/html 三种输出；--as-user 触发团队汇总与成员对比)
• 脚本: 见 scripts/dashboard_html.py(用途: 将统计看板生成为离线单文件HTML，含内联SVG图表，无需联网)
• 脚本: 见 scripts/auth.py(用途: 多用户与权限(RBAC)核心模块——角色/权限矩阵/范围解析/校验，供其他脚本复用)
• 参考: 见 references/industry-templates.md(何时读取: 首次使用时选择行业模板，或需要行业专属字段定义时)
• 参考: 见 references/field-definitions.md(何时读取: 执行结构化信息提取时，获取字段定义和AI提取提示词)
• 参考: 见 references/faq.md(何时读取: 遇到报错/环境/费用/粘贴文本等使用问题时查阅)
• 参考: 见 references/examples.md(何时读取: 想看完整样例——转写文本→结构化JSON→报告→看板时)
• 参考: 见 references/asr-alternatives.md(何时读取: 想了解火山引擎之外的ASR备选方案与费用对比时)
• 参考: 见 references/collaboration.md(何时读取: 需要理解多用户/团队/权限模型，或配置用户与角色时)

注意事项

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

安全说明（隐私与代码安全）

本技能在设计上遵循"数据本地化 + 最小权限"原则，已通过安全自查：

1. 数据不出本机：所有拜访数据仅写入本地 SQLite 文件（默认 ./visit_data.db），脚本不向外发送、不上传、不回传任何用户数据。
2. 唯一的外部网络调用：仅 scripts/asr_transcribe.py 在路径 A 下向火山引擎官方固定域名 openspeech.bytedance.com 发送音频用于转写；路径 B（手动粘贴文本）完全不联网。
3. 无危险执行：所有脚本均不使用 eval / exec / os.system；调用 ffmpeg/ffprobe 时以参数列表方式执行（无 shell=True），用户输入仅作为文件路径传入，不存在命令注入风险。
4. SQL 安全：数据库查询全部使用参数化占位符（?），表名/列名为代码内固定常量，不存在 SQL 注入。
5. 凭证处理：火山引擎密钥仅从环境变量 VOLCENGINE_ASR_API_KEY 读取，不写入任何文件、不打印到日志。
6. 依赖自动安装：requests / python-docx 首次运行缺失时自动 pip install，均为公开可信包。
7. 多用户权限隔离：团队协作模式下，所有读/写/删操作通过 --as-user 触发 RBAC 范围隔离（auth.py）。越权访问会在本地直接被拒绝，数据既不跨范围、也不出本机；用户口令以加盐哈希存储，不存明文。

> 若安全扫描对"外部网络访问"或"子进程调用"给出提示，属预期行为（即上述第 2、3 点），不影响本地数据安全。如介意，可直接使用路径 B 彻底避免联网。