> For AI agents: the complete documentation index is available at /llms.txt, the full documentation bundle is available at /llms-full.txt.

# 14. Ask AI：门店经营问答助手

> **版本边界（2026-10-03）**：本章保留的是 main 旧版读取能力盘点，以下“当前”及限制只对应该盘点，不应当作最新 test feature 的状态。独立分支在 test 完成了官方 Agent runtime、自带 API key、当前 Task context、可点击引用及 Next Action 改期预览 → 人工确认的指定场景验收；代码尚未合并到 infra main、未进入 production。当前 PR 状态在下方 Ask AI 平台页维护。完整目标、设计图、实际截图和验收边界见 [Ask AI 平台](/ai/product/ask-ai-platform.md)，工程契约见 infra repo 的 `openwiki/studio/ask-ai.md`。

Ask AI 让用户用自然语言查询门店业务数据，把分散在客户、通话、短信、任务和报表里的信息整理成回答。例如：“这家店最近有哪些工作需要处理？”“这位客户之前沟通过什么？”“哪些通话值得拿来培训员工？”

**当前能力是读取业务数据、汇总情况和辅助判断。** 它可以说明问题、提供依据和建议，但不能通过聊天发送短信、拨打电话、创建或关闭任务，也不能修改门店设置。实际操作仍需进入对应业务页面。

本章按当前本地前后端代码整理；提问示例说明工具支持的使用方向，不代表已经在生产环境逐题验收。

## 快速了解：Ask AI 不能做什么

- **不能替人执行操作**：不能发短信、拨电话、修改客户、创建或关闭任务、批准 AI 提案，也不能改门店设置或话术。
- **不能查询所有门店**：只查你有权限、已激活且开启 Ask AI 的门店，一次最多 50 家。
- **不能自动理解你正在看什么**：不会自动带入当前页面、客户、门店或日期筛选，提问时需要说明。
- **不能任意查历史、拿全量数据**：多数查询只支持最近一段时间，列表有条数上限，没有无限翻页或完整导出。
- **不能直接提供完整原始证据**：不能播放录音、读取完整逐字稿；摘要可能截断，回答引用暂不能点击跳转。
- **不能保证分析结论完全正确**：引用校验不等于结论正确，部分统计口径与页面不同；收入金额是估值，不是实际到账。
- **不能主动定时发经营日报**：需要用户提问触发，当前也没有默认启用联网搜索。

另外，两项查询还没完全打通：**不能直接筛出全部“从未联系”的线索明细；从任务列表继续追问单个任务详情也不够可靠。** 各项限制的具体原因见下文对应模块。

## 1 入口、使用资格与查询范围

Ask AI 以登录后页面中的悬浮按钮提供入口，点击打开对话面板。它是全局助手，可以跨页面使用。

| 条件     | 当前规则                                                                                                      |
| ------ | --------------------------------------------------------------------------------------------------------- |
| 环境开关   | 部署环境必须启用 Ask AI                                                                                           |
| 门店开关   | 用户可访问的门店中，至少一家已激活并开启 Ask AI，才显示入口                                                                         |
| 使用角色   | Owner、Editor、Viewer 均可查询自己有访问权的合格门店；后台没有把提问限定为 Owner                                                      |
| 门店设置权限 | 开启或关闭门店 Ask AI 属于 Owner 的 Store Setup 设置权限，参见 [Store Setup](/funding-strategy/02-产品说明书/12-store-setup.md) |
| 本次查询范围 | 当前用户可访问、已激活且开启 Ask AI 的门店，最多纳入 50 家                                                                       |
| 多店账号   | 可查询单店，也可以询问授权范围内的多店情况；不会自动获得整个品牌或其他加盟商的数据                                                                 |

**当前页面选择的门店，不会自动成为提问范围。** 前端只发送问题和会话标识，不附带正在查看的客户、页面、门店或日期筛选。因此，询问单店时应写清店名；询问某个人时应提供姓名或号码，不能只说“这个客户”。

后台在接收问题时固定本次门店范围，执行时再次检查这些门店是否仍处于激活且开启 Ask AI 的状态。超过 50 家时当前会截取其中 50 家，不应把回答当作完整门店网络的汇总。

## 2 对话面板：提问、追问与查看依据

| 功能               | 操作与表现                                  |
| ---------------- | -------------------------------------- |
| 输入问题             | 支持自然语言；提示词要求按用户提问语言回答。单次问题最多 2,000 个字符 |
| 发送               | 点击发送按钮或按 Enter；Shift + Enter 换行        |
| 等待回答             | 显示 Thinking；同一面板等待期间不能继续发送             |
| 阅读结果             | 展示文字回答、引用标签，以及可能出现的警告信息                |
| 连续追问             | 可以围绕上一问题继续问，后台带入最近 10 轮已成功问答作为上下文      |
| New conversation | 清空当前面板并开始新会话；不是删除后台记录，也不是取消已经提交的查询     |
| 关闭面板             | 收起聊天界面                                 |

前端最多保留最近 50 条消息，包括提问和回答；当前没有按日期浏览、搜索或切换历史会话的完整管理界面。

回答下方的引用用于标识本次查询得到的客户、通话、短信、任务或统计依据。**当前引用标签不能点击跳转到原始业务记录**，需要回到相关页面核对。后台会检查引用是否来自本次查询，但这不等于已经验证回答中的每一句推论；没有引用或引用无效时，回答可能仍然展示，并附带警告。话术查询也没有生成与其他业务记录相同的引用标签。

## 3 门店经营概览与多店比较

### 3.1 看一家店当前需要关注什么

Ask AI 可以结合门店工作快照和经营概览，整理未完成工作、逾期任务、相关员工，以及近期电话、短信和线索活动。

适合用来快速了解“哪里需要进一步检查”，然后进入 Tasks、Leads 或 Calls 处理。

> 示例：“West Harlem 最近 7 天有哪些工作需要我关注？分别说明任务积压、逾期情况和近期沟通情况。”

### 3.2 比较多家门店

多店比较可以并排展示不同门店的线索、联系、预约、通话和任务相关指标，并提供汇总。各门店按自己的时区计算报告窗口。

> 示例：“比较我有权限且开启 Ask AI 的门店最近 7 天的表现，指出线索联系、预约和任务处理上的差异，并列出依据。”

当前多店比较工具要求至少两家店，输入只有时间窗口，没有指定门店子集的参数。它会比较本次查询范围内的门店；不能承诺“只比较指定的两家”始终通过同一个比较工具完成。

这些结果可以帮助发现差异，但不能仅凭数量高低断言某家店经营更好。门店规模、数据完整性、电话类型和统计窗口都需要一起考虑。

## 4 客户查询：把一个人的情况串起来

这个模块用于回答“这个人是谁、最近发生了什么、还需要跟进什么”。

| 查询内容 | 能提供的信息                                  |
| ---- | --------------------------------------- |
| 找到客户 | 按完整或部分姓名、电话号码搜索，返回客户及所属门店               |
| 客户概况 | 线索状态、会员阶段、意向、禁止联系标记、投诉、待行动信息和已有客户摘要     |
| 最近电话 | 查询该号码近期的通话，再读取某通话的分类、结果、原因、摘要、跟进信息与证据片段 |
| 最近消息 | 查询短信、语音留言及其已有文本内容                       |
| 客户任务 | 查看未完成任务、近期已关闭任务，以及近期客户时间线事件             |

> 示例：“查一下 West Harlem 的客户 Jane Smith，整理她最近的沟通、当前状态和仍需处理的任务。如果有同名客户，先让我确认是哪一位。”

同名客户可能不止一人，同一号码也可能存在于多家授权门店。提示词要求遇到多个匹配对象时先确认，不能凭姓名猜测身份。搜索最多返回 6 个候选，匹配过多时需要补充姓名或号码。

客户摘要、消息和通话证据都有长度限制，回答不能替代完整原始记录。通话详情工具读取的是已经生成的分析结果，**不会在聊天中重新听录音，也不提供原始逐字稿全文**。

## 5 沟通查询：电话、短信与未读会话

除了按客户查询，Ask AI 也可以从门店整体查看近期沟通。

| 功能      | 适合回答的问题                      | 使用边界                 |
| ------- | ---------------------------- | -------------------- |
| 门店通话清单  | 最近有哪些电话，由谁接待，结果怎样            | 提供近期部分记录和总数，不是完整通话导出 |
| 通话分析    | 电话主要涉及什么业务，预约、销售、挽留和跟进原因怎样分布 | 可控制是否包含语音留言；应明确统计口径  |
| 短信会话清单  | 最近与哪些客户有短信往来，哪些会话显示未读        | 提供最新消息预览，可按未读筛选      |
| 单客户沟通回顾 | 某个人最近打过哪些电话、发过什么消息           | 与客户查询模块配合使用          |

> 示例：“查看 West Harlem 今天的通话，并总结最近 7 天主要的跟进原因；另外列出当前查询范围内最近 7 天的未读短信会话。”

“未读会话”的当前筛选条件是**最新一条短信为客户发来的未读消息**，不能直接等同于“所有尚未回复的客户”。它也不会代替员工回复这些消息。

## 6 任务跟进：查待办、看趋势与安排

Ask AI 可以帮助经理了解工作量、积压位置和处理进展。

| 功能      | 当前支持                                          |
| ------- | --------------------------------------------- |
| 需要关注的任务 | 查询需要处理的任务、已安排任务、全部未完成任务或已关闭任务                 |
| 客户相关任务  | 把某客户的沟通和任务放在一起理解                              |
| 任务趋势    | 查看任务流入、关闭、重开、正向关闭、及时率，以及 AI 与人工关闭等指标          |
| 月份任务概况  | 查询当前全店未完成任务及缺少截止时间的数量，并查看这些任务在指定月份的较繁忙日期      |
| 单任务详情   | 后台具备按任务 ID 查询现状和近期事件历史的工具，但当前从列表继续追问详情的衔接仍有限制 |

> 示例：“West Harlem 现在有哪些需要员工处理的任务？再看最近 30 天任务新增和关闭的趋势，说明历史数据是否完整。”

月份查询支持 `YYYY-MM`，例如“2026-09”。未完成、缺少截止时间等总数统计的是当前全店未完成任务，不受月份限制；月份只用于这些任务的日期分布，不是该月份的历史任务快照。当前工具只返回最繁忙的 5 天等摘要，不返回整月逐日日历。

单任务详情要求真实任务 ID，而任务清单主要提供引用标签，没有直接给模型同样的 ID，也没有像通话详情那样通过引用解析。因此，不能把“从任一任务清单连续追问完整详情”描述成已经可靠打通的流程。

任务趋势会提供历史事件覆盖信息。历史不完整时，不能把记录减少直接解释成工作减少或效率下降。Ask AI 不会替用户改期、分配、关闭、重开任务或批准 AI 提案。

## 7 Lead 分析：线索进展与首次触达速度

这个模块帮助用户区分“来了多少线索”“有没有联系”“联系得是否及时”“是否推进到预约”。

| 功能            | 当前支持                                      |
| ------------- | ----------------------------------------- |
| Lead 漏斗       | 查看线索接入、独立客户、触达、联系、预约及任务覆盖，并与上一等长周期比较      |
| Speed to Lead | 查看首次触达速度、时间分布和未触达人数                       |
| Lead 清单       | 列出近期有效线索接入对应的客户，包含状态、最近接入时间及最近活动，可按线索状态筛选 |
| 客户进一步查询       | 找到某个人后，继续看其客户概况、沟通和任务                     |

> 示例：“West Harlem 最近 7 天收到多少线索、涉及多少独立客户？多少尚未首次触达，响应速度怎样，预约进展相比上一周期有什么变化？”

Lead 清单以窗口内的有效线索接入为基础，不是简单查询“最近创建的联系人”。老客户在窗口内再次提交线索，也可能出现在结果中。

当前没有单独筛选“从未首次联系”的 Lead 明细参数。因此，可以查询未触达人数，但不能保证直接列出全部未触达客户；也不能把最近返回的少量 Lead 当作完整漏跟进名单。

## 8 员工表现、Coaching 与话术参考

Ask AI 可以把表现统计与具体通话案例结合起来，辅助经理准备员工辅导。

| 功能          | 能查到什么                                        |
| ----------- | -------------------------------------------- |
| 员工表现        | 接待通话、预约、销售、挽留、表现与 coaching 相关统计，并单独列出员工任务关闭数 |
| Coaching 概况 | 待审核、已归档、未读等队列情况，以及通话覆盖情况                     |
| Coaching 案例 | 已有分析中的具体表达、问题和建议话术，可按员工姓名筛选                  |
| 现有 Scripts  | 列出门店有效话术，按名称查询话术内容，为建议提供参考                   |

> 示例：“整理 West Harlem 最近 7 天值得 coaching 的通话，说明员工说了什么、可以怎样改进，并参考门店现有话术。”

当前 coaching 案例最多返回 3 条，受可辅导标记、通话时长和员工归属等条件限制，并非所有通话都会出现。按员工筛选 coaching 概况时，审核队列会缩小到该员工，但覆盖率仍是全店口径，不应称为该员工个人覆盖率。

话术工具可以查已有内容，不能创建或修改 Scripts。匹配名称不够精确时，只取首个匹配话术；长内容会截断。

## 9 收入与机会：解释成交估值

Ask AI 可以查询门店的去重成交估值、发现的机会、体验课预约，以及部分无法恢复收入归属的任务；也支持与上一等长周期的成交估值比较。

> 示例：“查看 West Harlem 最近 30 天的成交估值、发现的机会和体验课预约，与上一周期比较，并指出哪些项目没有设置价格。”

**这里的金额按门店当前价格与去重成交计算，不是 POS 账单或实际到账收入。** 未设置价格表示金额未知，不能解读为零收入；发现的机会也不能直接当作已经成交。

当前收入工具没有跟随 Revenue 页面同一个报表开关。页面可能显示不可用，但工具仍能计算金额，因此不能告诉用户“这些数字一定已经显示在你的 Revenue 页面上”。

## 10 时间窗口、结果数量与口径限制

### 10.1 时间范围

多数报表接受“最近 N 天”，而不是任意历史起止日期。超过支持范围的天数会被截到工具上限。

| 查询类型                                                       | 默认范围    | 最大范围或例外                           |
| ---------------------------------------------------------- | ------- | --------------------------------- |
| 门店工作快照、Lead 漏斗、首次触达速度、Lead 清单、员工表现、通话分析、Coaching、多店比较、短信会话 | 最近 7 天  | 最近 30 天                           |
| 门店通话清单                                                     | 今天      | 最近 7 天                            |
| 单客户通话、短信及语音留言                                              | 最近 30 天 | 最近 90 天                           |
| 任务趋势、收入估值                                                  | 最近 30 天 | 最近 90 天                           |
| 月份任务概况                                                     | 门店当前月份  | 可指定 `YYYY-MM`                     |
| 门店健康概览                                                     | 固定组合窗口  | 组合使用近 30 天、本周/上周和近 7 天，不能统一指定 N 天 |

多数报表使用门店当地自然日，包含今天；单客户近期沟通使用滚动时间窗口，门店健康概览又有固定 UTC 窗口。不能把所有“最近 7 天”都视作完全相同的起止时间，也不能承诺任意历史月份的完整经营报表。

### 10.2 记录不是无限返回

| 列表            | 当前最多返回 |
| ------------- | ------ |
| 客户搜索          | 6 个候选  |
| 单客户近期通话或消息    | 各 15 条 |
| 单客户任务         | 12 条   |
| 门店任务          | 20 条   |
| 门店通话或 Lead 清单 | 各 30 条 |
| 短信会话          | 20 条   |
| Coaching 案例   | 3 条    |

这些列表没有供模型继续翻页的参数。多数查询另外返回总数，**展示条数不能当作业务总量**；摘要、消息、事件备注和话术也可能截断。目前没有聊天内的完整数据导出功能。

### 10.3 与页面核对时需要注意

部分工具复用页面的统计计算，但不能笼统承诺所有数字与页面一致：

- 多店比较中的通话按真人会话统计，页面默认口径可能包含语音留言。
- 门店号码配置缺失时，漏斗工具的触达或联系数可能输出零，而页面表达为未知；应先核对配置，不能立即判断“没有联系任何人”。
- Coaching 汇总没有完全套用当前用户在页面中的已读等筛选，员工筛选也不作用于所有覆盖指标。
- 收入工具与页面开关存在差异，金额本身又属于估值。
- 时间范围、门店范围、列表上限和历史事件完整度都会影响解释。

## 11 失败、缺失数据与尚未提供的能力

问题通过后台异步处理，前端等待结果，不是即时读取当前页面。查询失败或等待过久时会提示错误；应先核对店名、时间和权限，再按提示重试。后台限制同一会话只能有一个处理中问题，同一用户最多有三个处理中查询。

没有找到记录、数据缺失、工具无法回答和真实业务数量为零是不同情况。提示词要求模型在依据不足时说明限制，而不是编造客户、事件或数字；实际回答仍需结合引用和业务页面核对。

当前未提供以下能力：

- 通过聊天发短信、拨电话、修改客户或任务、调整门店设置。
- 直接点击回答引用跳转原始记录、播放录音或读取完整逐字稿。
- 任意 SQL 查询、无限翻页、完整历史数据导出。
- 由 Ask AI 主动定时生成并发送经营日报。
- 默认联网查询。代码保留可选网页搜索工具，但当前基础设施配置没有接入搜索密钥，不能按已启用功能介绍。

[Lead Line](/funding-strategy/02-产品说明书/10-lead-line.md) 与任务自动化有各自的执行链路；它们具备的行动能力不等于 Ask AI 对话框也能执行。

## 12 后台能力对应与实现依据

后台当前注册 24 个业务读取工具。以下映射用于核查功能覆盖，不需要用户记住工具名。

| 业务模块            | 对应工具                                                                                                            |
| --------------- | --------------------------------------------------------------------------------------------------------------- |
| 门店概览与多店比较       | `getStoreSnapshot`、`getStoreOverview`、`compareStores`                                                           |
| 客户概况与沟通回顾       | `searchContacts`、`getContactSnapshot`、`listRecentCalls`、`getCallDetail`、`listRecentMessages`、`listContactTasks` |
| 门店电话与短信         | `listStoreCalls`、`getCallAnalytics`、`listConversations`                                                         |
| 任务跟进            | `listStoreTasks`、`getTaskDetail`、`getTaskTrends`、`getTaskCalendar`                                              |
| Lead 分析         | `getLeadFunnel`、`getSpeedToLead`、`listStoreLeads`                                                               |
| 员工、Coaching 与话术 | `getStaffPerformance`、`getCoachingSummary`、`getCoachingExamples`、`getScripts`                                   |
| 收入与机会           | `getStoreRevenue`                                                                                               |

处理链路为：提交问题 → 后台固定门店范围并创建查询 → AI 调用业务读取工具 → 生成回答与引用 → 前端获取结果。业务工具使用只读数据库连接，但系统会保存问题、回答和查询状态，因此“只读”指不修改业务记录，并非完全不保存数据。

本章核查范围为本地代码，实际可用性以部署版本、开关配置和已有数据为准。

[入口与显示条件](https://github.com/retaintive/callytics-infrastructure/blob/main/apps/web/src/composables/useAskAiAvailability.ts) · [对话面板](https://github.com/retaintive/callytics-infrastructure/blob/main/apps/web/src/components/operator-chat/operator-chat-panel.vue) · [消息与引用](https://github.com/retaintive/callytics-infrastructure/blob/main/apps/web/src/components/operator-chat/operator-chat-message.vue) · [会话状态](https://github.com/retaintive/callytics-infrastructure/blob/main/apps/web/src/stores/operator-chat.ts) · [输入限制](https://github.com/retaintive/callytics-infrastructure/blob/main/apps/api/src/routes/v3/operator-contract.ts) · [查询接口与门店范围](https://github.com/retaintive/callytics-infrastructure/blob/main/apps/api/src/routes/v3/operator.ts) · [可访问门店](https://github.com/retaintive/callytics-infrastructure/blob/main/apps/api/src/utils/accessible-stores.ts) · [后台执行器](https://github.com/retaintive/callytics-infrastructure/blob/main/lambda/operator-agent/src/handler.ts) · [全部业务工具](https://github.com/retaintive/callytics-infrastructure/blob/main/lambda/shared/operator-chat/tools.ts) · [Coaching 案例筛选](https://github.com/retaintive/callytics-infrastructure/blob/main/packages/task-engine/src/metrics/coaching.ts) · [回答规则](https://github.com/retaintive/callytics-infrastructure/blob/main/lambda/shared/operator-chat/prompt.ts) · [会话历史与引用校验](https://github.com/retaintive/callytics-infrastructure/blob/main/lambda/shared/operator-chat/operator.ts) · [部署开关与搜索配置](https://github.com/retaintive/callytics-infrastructure/blob/main/lib/stacks/operator-agent-stack.ts)