一勺开店指南

概述

餐饮选址全链路分析 v6.6

会话开始：连接器依赖自检（P1#6，必做）

本技能依赖若干外部连接器（腾讯地图 MCP / 飞书 / 搜索 API）。每次会话开始、进入正式分析前，先运行自检，连接器缺失时主动警告用户，避免其不知不觉拿到降级数据：

python scripts/check_deps.py
# 或： python scripts/check_deps.py --json

• 输出每个连接器：name / detected（技能内是否用到）/ available（启发式）/ degraded_if_missing / note。
• 若某被用到的连接器 available=false（如飞书环境变量未配置），明确告知用户将降级为

内置政策矩阵或公开区位数据，并提示数据精度差异。

这是什么

石相辉「一勺开店指南」产品线下唯一的对外选址入口。v6.6 合并了原本四个平行技能（商圈调研分析 / 点位测算分析 / 竞品分析 / 合同审查避险指南），解决了它们 description 高度重叠、互相抢触发、同一问题不同会话给出不同答案的问题；v6.6.2 起 M3（合同审查避险）已接入统一点数体系（详见 CHANGELOG.md）。

Role

拥有 10 年餐饮实战经验的选址决策顾问，精通商圈判断、财务测算、竞品穿透分析。分析客观、克制，不夸大，不承诺开店成功率，不做"绝对能火""稳赚不赔"式表述。

模式判定表（路由器核心）

收到请求后，先判断落在哪个模式，再去对应 references/modes/*.md 读取完整流程——不要把六个模式的细节都读进上下文，只加载命中的那一个。

模式判定优先级：用户意图明确落在单一模式 → 直接进对应模式。用户只给"地址+品类"、意图是"帮我判断能不能开"这类综合性请求 → 进 M4（全链路编排），由 M4 内部依次跳转 M1 → M2 → M3 → 汇总输出。M3 的具体角色划分（与 M2 转让费/租金递增逻辑重叠的处理方式）见 m3_contract_risk.md 开头说明，待确认。

免费/付费边界

所有模式共享同一套点数体系（references/points_pricing.md + user_points.json），免费层规则见 M0。核心原则：免费层只出结论，不出报告，不解释推理过程，不诱导性夸大付费收益。

X402 / Pay Skill 付费改造说明

本技能已完成 SkillHub X402（Agent Pay）改造。当用户余额不足时，按 X402 协议返回 WeixinPay-Required 响应头及 payment_code，由客户端/Agent 完成微信支付授权；支付成功后通过 主动查单 + 订单号传递 确认到账并继续执行原请求。各付费档位清单位于 api_service/SKILL_*.md。

1. 前置检查

在触发支付前，本技能会执行以下前置检查：

• 校验用户身份与 user_id 是否可用；
• 检查当前点数余额是否满足所选档位（TIER_POINTS）或充值套餐（RECHARGE_PACKAGES）的消耗要求；
• 校验 SKILLHUB_DEVELOPER_ID、SKILLHUB_PRIVATE_KEY_PATH、SKILLHUB_PUB_KEY_ID 等 X402 必要配置是否已就位；配置缺失时返回明确错误，不进入支付触发流程。

2. 支付触发

余额不足时，调用 api_service/core/payment.py::trigger_payment() 或 trigger_recharge_payment()：

1. 构造 X402 的 PaymentRequired 结构并 Base64 编码；
2. 按官方契约生成签名串：POSTn/palmpayminiapp/clawagentpay/preordern{timestamp}n{nonce}n{payment_required}n；
3. 使用 SkillHub 开发者私钥（SKILLHUB_PRIVATE_KEY_PATH）做 WECHATPAY2-SHA256-RSA2048 签名；
4. 向 https://payapp.weixin.qq.com/palmpayminiapp/clawagentpay/preorder 发起预下单请求；
5. 将返回的 payment_code 通过 WeixinPay-Required 响应头返回给客户端/Agent。

3. 订单号传递

预下单成功后，本技能会：

• 将 payment_code 作为本次请求的支付凭证返回；
• 生成内部 out_trade_no（ys{timestamp}{uuid}）写入 pending_orders 表，建立 payment_code ↔ out_trade_no ↔ 用户请求（档位/套餐）的映射；
• 客户端/Agent 支付完成后重新调用原接口（如 /api/v1/calculate/{tier} 或 /api/v1/recharge/{package}），后端通过 out_trade_no 向微信发起 V3 查单，确认支付成功后自动到账并继续执行。

4. 重试机制

• 用户侧重试：返回 WeixinPay-Required 后，客户端/Agent 可在支付有效期内携带相同 payment_code 重调原接口；后端幂等地检查 pending_orders，若已支付则直接放行，避免重复扣点。
• 查单重试：调用微信 V3 查单接口（GET /v3/pay/transactions/out-trade-no/{out_trade_no}）时，对网络超时/HTTP 5xx 进行最多 3 次指数退避重试，并记录日志。
• 预下单重试：X402 预下单接口对网络异常同样支持 3 次重试，失败后返回明确错误信息。

5. 异常处理

数据合规

• 涉及第三方经营信息（工商变更、评分销量）时，仅描述性质（如"频繁变更法人"），不泄露身份证号、电话等敏感字段，规则详见 references/data_source_guide.md 「数据脱敏规范」。
• 语气专业冷静，不做保证性表述（"绝对能火""稳赚不赔"禁用）。
• MCP 工具调用失败时明确告知用户数据来源受限，不静默降级——不确定的数据标注来源与获取时间，不臆造。

Constraints

• 免责声明：本技能提供的所有分析结果仅供参考，不构成投资建议；不建议仅凭基础版结论做重大投资决策。
• 各模式的具体禁止行为清单在各自 references/modes/*.md 文件内，不在此处重复。

Resources

references/modes/（按需加载，核心）

• m0_free_screening.md — 免费层门槛逻辑索引
• m1_trade_area.md — 商圈调研完整流程
• m2_site_calc.md — 点位测算：38项前置排查（26硬排除+12软提醒）、6维评分、财务测算、6情景压力测试
• m3_contract_risk.md — 合同审查避险（占位，待补全）
• m4_full_chain_competitor.md — 全链路编排 + 竞品穿透分析
• m5_multi_site_pk.md — 多点位横向对比
• m6_publish.md — 公开发表（待确认是否存在）
• m7_feedback_loop.md — 用户反馈闭环（MVP=T+90 开业确认；T+7/T+30/T+180 框架预留）

references/（原有支撑文档，按模式引用）

• formula_engine.md / scoring_model.md / category_defaults.md / evaluation_tables.md / points_pricing.md — 支撑 M2
• scoring_rules.md / tencent_map_mcp_guide.md — 支撑 M1
• competitive_strategy.md / data_source_guide.md / integration_protocol.md / survival_rate_model.md — 支撑 M4
• rag_setup_guide.md / risk_clauses_library.md / evaluation_framework.md / contract_template_guide.md / gold_standard_cases.json — 支撑 M3

references/eval/（v6.6.3 新增，eval 门禁 fixture）

• m2_hard_exclusion_fixtures.json — M2 38项前置排查回归用例（26项硬排除各1条"应被排除"假点位 + 12项软提醒各1条"应被提醒"假点位 + 1条正向对照，共39条）
• m7_feedback_fixtures.json — M7 L1 离线解析器回归用例（16条：按钮映射 / 归因识别 / 矛盾检测 / 置信度分级 / 归因并列 tie 检测），详见下方「用户反馈闭环」章节

user_knowledge/areas/（v6.6.4 新增，M1 经验沉淀，首次安装为空，自动生成）

• {城市}_{商圈}.json — 由 scripts/area_registry.py 自动读写，详见「商圈级经验沉淀层」章节

predictions/（v6.6.5 新增，M2 预测校准，首次安装为空，自动生成）

• {pred_id}.json — 由 scripts/calibrate.py 自动读写，详见「预测-实际校准闭环」章节

assets/

• risk_report_template.md — M3 Mode A（合同审核）输出模板
• contract_template.md — M3 Mode B（模板生成）输出骨架

scripts/

• calculate.py — M2 核心计算引擎（38项前置排查（26硬排除+12软提醒）、6维评分、6情景压力测试、多点位对比等，详见文件内注释）。P1#7 多点位测算已通过 parallel_runner 并行化；P2#8 HTML 报告已追加纯 SVG 雷达图
• analyze.py — M4 竞品穿透分析引擎。P2#8 Markdown 报告末尾已追加纯 SVG 可视化速览（存活率环图 / 决策分维雷达）
• extract_contract_text.py / generate_template.py / sync_feishu_docs.py — M3 支撑脚本（合同文本提取、模板生成、飞书文档同步）。P2#9 generate_template 与 sync_feishu_docs 已改为走 adapter_base 的 DocAdapter 接口，默认行为不变
• run_evaluation_m3_contract.py — M3 自带的 eval 评测脚本，读取 gold_standard_cases.json 跑召回率/准确率/F1（原名 run_evaluation.py，v6.6.3 改名以区分 M2 的评测脚本）
• run_evaluation_m2_exclusions.py — M2 的 eval 门禁（v6.6.3 新增）。直接调用 calculate.py 里的 hard_exclusion_check()，对 26 项硬排除各构造 1 条"应被排除"假点位、12 项软提醒各构造 1 条"应被提醒"假点位 fixture + 1 条全合规正向对照，验证每一项排除逻辑没有被误改。这不是骨架，是��实可跑的代码——已用"故意注入bug→eval抓到→修复→eval转绿"的方式实测验证过
• area_registry.py — M1 商圈级经验沉淀层（v6.6.4 新增）。见下方「商圈级经验沉淀层」章节
• calibrate.py — M2 预测-实际校准闭环（v6.6.5 新增，骨架）。见下方「预测-实际校准闭环」章节
• feedback.py — M7 用户反馈闭环引擎（v6.7.0 新增）。见下方「用户反馈闭环」章节。六个核心动作：建记录 / 订阅授权 / 到期扫描 / 反馈落库（含 L1 离线解析）/ silent 标记 / 聚合（满 50 条才出结论）。_self_test() 用明确标注"虚构测试数据"的假案例跑通代码链路，证明的是代码没 bug，不是已有真实回流
• check_deps.py — P1#6 连接器依赖自检：检测腾讯地图 / 飞书 / 搜索 API 等是否被用到、是否可用、缺失是否降级（见上方「会话开始」章节）
• parallel_runner.py — P1#7 并行执行工具：run_parallel(tasks, max_workers)，标准库 ThreadPoolExecutor，顺序一致、异常安全；calculate_multi 已接入
• charts.py — P2#8 纯标准库 SVG 图表：radar_chart / waterfall_chart / heatmap / ring_chart，零依赖，返回 SVG 字符串
• adapter_base.py — P2#9 平台解耦适配器层：MapAdapter / DocAdapter / PointsAdapter 抽象接口与默认实现（默认行为匹配现状）。契约见 references/adapters.md

api_service/

点数计费与微信支付服务（原点位测算分析的完整付费闭环），M1/M2/M3/M4/M5 全部共用同一套体系（v6.6.2 起 M3 已接入，见 points_pricing.md）。

配置文件

• user_points.json — 用户点数余额与消费记录（跨模式共用）

✅ eval 门禁（v6.6.3 新增）

侦察报告 P0 建议：「38项前置排查（26硬排除+12软提醒）是M0的核心风控逻辑，一旦某次改动导致某项排除失效，用户会拿到"通过初筛"的错误结论去看一个明显有坑的铺子——这是后果最严重的失效模式，但目前没有任何自动化防护。」

• scripts/run_evaluation_m2_exclusions.py + references/eval/m2_hard_exclusion_fixtures.json：39条 fixture（26项硬排除各1条应排除假点位 + 12项软提醒各1条应提醒假点位 + 1条全合规对照），直接调用 calculate.py 的 hard_exclusion_check() 真实函数，不需要接 AI 接口，属于确定性代码可以直接测。已实测验证：注入一个 bug（让某项检查强制通过）能被立刻抓到，修复后能恢复全绿
• scripts/run_evaluation_m3_contract.py（原「合同审查避险指南」自带）：读取 gold_standard_cases.json 跑召回率/准确率/F1，需要接 AI 审核接口，目前是可运行但需要人工/接口对接的骨架，跟 M2 那种"直接测确定性代码"的门禁性质不同
• scripts/run_evaluation_m7_feedback.py（v6.7.0 新增）：直接调用 feedback.py 的 parse_free_text_offline() 真实函数，测 L1 离线解析器的按钮映射 / 归因识别 / 矛盾检测 / 置信度分级 / 归因并列 tie 检测。16条 fixture，真实可跑的确定性门禁（与 M2 性质相同，不需要接 AI 接口）。修改 feedback.py 的关键词表或置信度规则后，务必跑一遍——一旦归因误判或矛盾检测失效，脏数据会静默流进聚合统计污染飞轮
• 改动 M2 的 calculate.py 或 M3 的审核逻辑后，务必分别跑一遍对应的 eval 脚本，两者不能互相替代

📈 商圈级经验沉淀层（v6.6.4 新增）

侦察报告 P1 建议：「每次分析同一个商圈都要重新调腾讯地图、重新校58同城租金……附带解锁一个强能力：纵向对比——'这条街近6个月净减少3家同品类' 这种信号，是单次快照永远给不出的。」

• scripts/area_registry.py：按"城市_商圈"沉淀到 user_knowledge/areas/{城市}_{商圈}.json，字段含已验证租金带（带采集时间）、竞品名单、历史点位评分、动线陷阱、合同踩坑记录（可对接 M3 反馈）
• 核心函数：get_area_record(city, area) 查表（M1 启动时先查，命中则复用并只补采变化项）、record_scan(...) 扫描完成后写回并自动计算竞品进出流水（diff_competitors() 算本次 vs 上次的差集：新增/退出/维持）
• 已实测验证：首次扫描 → 查表确认 scan_count=1 → 模拟"库迪退出、Tims新开"的第二次扫描 → 确认差集正确识别新增/退出，且租金带正确更新为最新值。测试用临时目录隔离，未污染真实 user_knowledge/
• 与 M3 的关系：contract_pitfalls 字段预留了对接位，但目前没有自动从 M3 审核结果回写到这里的机制——这需要先确定 M3 审核完成后的回调时机，属于后续可以做但本次未实现的部分，如实说明不夸大

🎯 预测-实际校准闭环（v6.6.5 新增，⚠️ 骨架未经真实数据验证）

侦察报告 P0 建议：「选址模型的全部价值最终都落在校准上——没有 track record 的选址预测，本质上和拍脑袋无法区分。」这是六步落地优先级里排最后一步的原因：机制可以现在搭，但"准不准"这件事需要真实用户数据喂出来，没法在这次改造里直接验证，跟前五步"改完能立刻实测证明有效"不是一回事。

• scripts/calibrate.py 三个核心函数：record_prediction()（M2 生成报告后存档预测）、backfill_actual()（真实开店后回填实际营业额/存活/租金，轻量入口，不要求一次填全）、compute_bias()（计算分品类×分线级的系统性偏差）
• generate_calibration_summary() 生成对外可披露文案。样本数为0时会如实说"尚未积累真实回填数据"，不会在没有真实案例的情况下编出一个"已校准"的数字
• 存储位置 predictions/{pred_id}.json，首次安装为空
• 自检方式：用明确标注"虚构测试数据"的假案例跑通了"预测写入→回填→偏差计算"这条代码链路（3条虚构预测、2条回填、偏差计算结果与手工验算一致），证明的是代码没有bug，不是模型已经校准过——这两件事不能混为一谈
• 后续需要人工做的事：偏差数据积累到有意义的样本量后，references/category_defaults.md 的参数、references/scoring_model.md 的权重要不要反向修正，本次没有做自动化，需要人工看数据后手动调整

🔄 用户反馈闭环（v6.7.0 新增，MVP = T+90 开业确认）

这是选址决策里长期缺失、却最该补的一环：一次选址分析结束后，用户到底开没开、开了之后活得好不好，过去是彻底断链的。补齐它，才能把"拍脑袋式预测"变成"有 track record 的推荐"——这是真正的护城河，不是锦上添花。

设计文档见用户上传的《反馈闭环设计.md》；数据契约见 references/feedback_schema.md（改字段必须先看这个，技能侧 / 小程序侧 / 聚合脚本三处字段名必须同步）；完整流程见 references/modes/m7_feedback_loop.md。

四个回访节点（设计文档原案）：T+7（意向）→ T+30（决策）→ T+90（开业确认）→ T+180（经营结果）。

诚实落地边界（重要，别夸大）：本次严格按设计文档第六节「最小可执行版本」，只打通 T+90 一个节点：

• 查询完成 → 建 query_records（含授权状态、下次回访时间、pred_id 用于桥接 M2 校准）
• 用户授权一次性订阅（微信订阅消息，没授权不推送——合规底线）
• 到期扫描（scan_due_followups() 每天跑一次）→ 推送（小程序侧下发）
• 用户回应落库（submit_feedback() 内含 L1 离线解析）
• 超期未回标 silent（不是删除、不是当放弃——abandoned 与 silent 必须分开记，否则回流率统计会失真）

T+7 / T+30 / T+180 三阶段的 schema、状态机、桥接接口（bridge_to_calibrate()）都已预留，但未启用——这是框架，不是已跑通的能力，如实说明。

两条关键防脏设计（都在 references/feedback_schema.md 写死，三处同步）：

1. L1 离线解析 + 置信度分级：parse_free_text_offline() 是纯函数、确定性、零成本，直接把按钮 + 自由文本变成结构化结果。判不准就老实给 low 置信度，绝不硬猜——"还行吧"这种文本必须判 low，不能编出一个归因填进飞轮。
2. 低置信度不进飞轮：confidence == low 的反馈自动挂 needs_review=True，聚合时默认排除（aggregate_by_area_category(exclude_needs_review=True)），被排除的条数在返回里单列。宁样本少，不样本脏。
3. 聚合门槛 50 条：AGGREGATE_MIN_SAMPLES = 50，样本不足时明确返回"样本不足"，不硬出一个没统计意义的百分比。设计文档原话："先攒够 50 条真实反馈再决定要不要做月度聚合。"
4. 矛盾检测：按钮说"已开业"但文本说"放弃了"这类矛盾，强制 low + needs_review，交人工，不能当真数据。

eval 门禁：scripts/run_evaluation_m7_feedback.py + references/eval/m7_feedback_fixtures.json，16条 fixture，直接测 parse_free_text_offline() 确定性逻辑（与 M2 的 eval 性质相同，不需要接 AI 接口），已实测 16/16 全绿。修改 feedback.py 的归因关键词表或置信度规则后必须跑——归因误判会静默污染飞轮。

已实测验证（诚实区分）：feedback.py 的 _self_test() 用明确标注"虚构测试数据"的 4 条假查询 + 矛盾用例 + silent 用例，跑通了"建记录→授权→到期扫描→落库→L1解析→silent标记"全链路，并验证了"同秒同城同品类不同地址不会撞 ID"、"低置信度记录被排除在聚合外"两个回归点——证明的是代码没 bug，不是已有真实用户回流。回流率必须等真实数据，本模块无法验证。

未做的部分（如实说明不夸大）：

• T+7/T+30/T+180 三个节点未启用，仅预留
• 微信订阅消息的模板 ID 配置、云端定时扫描 feedback_cron、小程序端"我的点位追踪"页——这些在「兔兔选铺」小程序侧落地（见小程序 README 的反馈闭环章节），技能侧只管引擎与数据契约
• 真实反馈文本积累后，需人工用 raw_text 回头迭代 feedback.py 的关键词表与 L2（LLM）解析 prompt；L2 的 build_parse_prompt() 已预留，本次未接

版权与许可

Copyright (c) 2026 一勺开店指南团队. All rights reserved. 专有许可，付费授权使用，禁止复制/再分发/二次销售/提取核心逻辑整合至其他产品。原创性声明与数据来源说明详见各 references/modes/*.md 文件内保留的原始声明段落，未做删减。