三体云智能AI助手

概述

三体云动 SaaS 能力路由

⚠️ Skill 命名策略（必读）

先加载顶层 santi。业务域文件在 Hermes 中可能以 santi/auth、santi/member 等路径展示，也可能在 skill 列表里显示为 category=santi、skill_name=auth / member / course / finance / order / operation。

1. 顶层入口只加载 santi；不要尝试加载 santi:santi。
2. 鉴权和门店切换：优先加载 santi/auth；如果 skill_view 只列出 category=santi 的 auth，则加载 auth。
3. 会员查询：优先加载 santi/member；如果 skill_view 只列出 category=santi 的 member，则加载 member。
4. 课程排期：优先加载 santi/course；财务报表：santi/finance；订单交易：santi/order；门店运营：santi/operation；Excel 导出：santi/export。
5. 裸名 auth / member / course / finance / order / operation / export 只有在可用 skill 列表显示其 category 为 santi 时才表示本包业务域；若存在同名其他 category，必须选择 category=santi 的条目。
6. 不要加载 santi.bak:*，点号不是合法 namespace；备份目录不应放在 Hermes skills 目录内。
7. 本文件不含 references/ 目录：各业务域说明见对应子目录的 SKILL.md 和 references/api.md。各域 mcp.json 是动作 schema 参考；真正一等工具来自标准 Santi MCP server。

⚠️ 文件访问约束（必读）

• skill_view 工具只能查看当前 skill 目录内的文件，无法跨目录访问其他 skill 的文件。
• scripts/gateway_api.py 等共享脚本位于 ~/.hermes/skills/santi/scripts/，禁止通过 skill_view 查看，必须通过 run_in_terminal 执行。
• 如需查看脚本内容，使用 run_in_terminal 执行 cat ~/.hermes/skills/santi/scripts/gateway_api.py。

执行环境

MCP 优先策略（MANDATORY）

如果当前 client 已注册 Santi MCP server，必须优先调用 MCP 工具，不要走 terminal：

mcp_santi_login
mcp_santi_status
mcp_santi_getShopList
mcp_santi_switchShop
mcp_santi_listCapabilities
mcp_santi_getCapability
mcp_santi_memberCall
mcp_santi_courseCall
mcp_santi_financeCall
mcp_santi_orderCall
mcp_santi_operationCall
mcp_santi_exportCall
mcp_santi_excelExport
mcp_santi_memberDetail
mcp_santi_memberCreate

Dashboard 首页看板、会员/课程/营收分析等 dashboard.* 接口通过mcp_santi_financeCall 调用。

只有 MCP 工具不存在、不可用或用户明确要求 fallback 时，才使用下方固定脚本入口。

可扩展 MCP 调用策略（几百接口场景）

默认优先使用域级通用工具，而不是为每个接口寻找独立 MCP 工具：

使用流程：

1. 不确定 method 时，先调用 mcp_santi_listCapabilities(domain) 查看该域白名单。
2. 需要确认描述时，调用 mcp_santi_getCapability(method)。
3. 调用 <domain>Call(name, method, params)；method 必须属于该域 catalog 白名单。
4. 只有登录、状态、门店切换、会员详情/创建等高频或强状态动作优先用一等工具；新增接口默认不新增 MCP tool。

默认 MCP 服务只注册上述精简主干工具。旧版高频/兼容快捷工具（如mcp_santi_scheduleTeam、mcp_santi_orderList、mcp_santi_staffList 等）仅在服务启动参数包含 --enable-compat-tools 或环境变量SANTI_ENABLE_COMPAT_TOOLS=1 时注册。默认模式下不要寻找这些快捷工具，应通过对应域级通用入口调用。

MCP 工具返回 JSON 字符串，其中 ok=true 且 api_response_verified=true / request_id 存在，才表示真实后端 API 调用成功。status 是本地状态检查，不要求 api_response_verified=true。

前置条件检查（所有请求必过）

shop_id=0 只表示当前 access_token 处于品牌态，常见于多门店账号刚登录后；这不是登录失败。登录、status、getShopList、switchShop 允许在品牌态执行，Dashboard 品牌/门店通用接口也允许品牌态执行；会员、订单、排期等门店明细接口才需要先切到具体门店。

意图路由表

高频意图优先级（老板口语）

以下规则优先于单个关键词命中，避免把老板口语误路由到相邻接口：

1. 生意/经营概览：用户问“今天/本月店里怎么样”“生意好吗”“整体数据”“做到多少了”等宽泛经营问题，优先转 finance，用 dashboard.*.top-profile 或 report.revenue-total；不要只调用 dashboard.common.course-analysis。
2. 销售排行/排名：用户问“销售排行榜/销售排名/谁卖得最好/业绩排名”等，优先 finance 的 report.sales-ranking；不要路由到课程排行或上课分析。
3. 会员实体优先会员域：用户提供手机号、姓名，或说“这个会员/他/她”，并询问会员卡、储值卡、课程包、私教、小班课、体验卡、预约、入场、来店、到店、跟进、孩子等会员资产/记录时，优先 member 的对应子接口。不要因为出现“课/预约”就转到 course。
4. 会员卡必须查卡接口：用户问“还有会员卡吗”“会员卡是否有效”“会员卡剩几天/什么时候到期”等，memberDetail 只能确认会员身份，必须继续调用 member.member-card。
5. 门店课程存量：用户未提供会员姓名/手机号，只问“现在还剩多少课时”“剩余课时金额”“未消课负债”等，转 finance.report.brand-course-overview。只有带具体会员实体时，才转 member 的课程资产接口。
6. 指定教练排期：用户给出教练姓名/昵称并问“课表/排班/忙不忙/本周安排”，或说类似“短发短你好本周课表”“看下短发短你好今天忙不忙”，转 course.schedule.coach-schedule；只有用户明确说“我/我的课表/我的排期/我今天有什么安排”且没有点名其他教练时，才转 course.schedule.my。我是教练 只是角色背景，不等于“我的排期”。
7. 教练上课统计：用户问“私教上课统计”“团课上课统计”“我这个月私教上课统计”等统计口径时，转 finance.report.personal-coach-stat 或 finance.report.team-coach-stat；不要转 dashboard.common.course-analysis，除非用户明确问上课分析、课程排行或消课分析。
8. 教练名单不是排期：用户问“教练有哪些”“私教教练名单”“团课教练看下”，转 operation.staff.list；只有问“团课排期/团课表/今天有什么团课”才转 course.schedule.team。

模糊意图消歧规则

当用户表述可能匹配当前域「接口决策表」中的 2 个及以上接口时：

1. 上下文推断优先：若本轮/上轮对话含可唯一锁定接口的线索（实体名、关键词、前序操作），直接路由，无需询问。
2. 无法推断则必须澄清：禁止猜测调用。从接口决策表中筛选所有可能匹配项，以编号列表展示给用户选择：

   请问您想查看哪个？
   1. <接口意图> — <一句话说明>
   2. ...
   请回复数字或直接说明。

1. 禁止全量调用：不得为了"全面"而并发调用多个候选接口。

固定脚本入口（Fallback）

仅当 MCP 工具不可用时，才使用以下稳定入口；不要手写 curl，不要用 execute_code 读写 token，不要直接 cat token 文件：

GATEWAY_DOMAIN=<网关域名> SANTI_TOKEN_DIR=~/.santi-mcp/tokens python3 ~/.hermes/skills/santi/scripts/gateway_api.py login --name <账号> --password '<密码>'
GATEWAY_DOMAIN=<网关域名> SANTI_TOKEN_DIR=~/.santi-mcp/tokens python3 ~/.hermes/skills/santi/scripts/gateway_api.py status --name <账号>
GATEWAY_DOMAIN=<网关域名> SANTI_TOKEN_DIR=~/.santi-mcp/tokens python3 ~/.hermes/skills/santi/scripts/gateway_api.py getShopList --name <账号>
GATEWAY_DOMAIN=<网关域名> SANTI_TOKEN_DIR=~/.santi-mcp/tokens python3 ~/.hermes/skills/santi/scripts/gateway_api.py switchShop --name <账号> --shop-id <shop_id>
GATEWAY_DOMAIN=<网关域名> SANTI_TOKEN_DIR=~/.santi-mcp/tokens python3 ~/.hermes/skills/santi/scripts/gateway_api.py memberDetail --name <账号> --keyword '<手机号或姓名>'
GATEWAY_DOMAIN=<网关域名> SANTI_TOKEN_DIR=~/.santi-mcp/tokens python3 ~/.hermes/skills/santi/scripts/gateway_api.py excelExport --name <账号> --export-type cashier_collect --day 30
GATEWAY_DOMAIN=<网关域名> SANTI_TOKEN_DIR=~/.santi-mcp/tokens python3 ~/.hermes/skills/santi/scripts/gateway_api.py call <method> '<params_json>' --name <账号>

登录、状态、门店切换、常用会员查询和 Excel 导出优先使用固定子命令；课程、订单、财务、运营等新增域的 terminal fallback 统一使用 call <method> '<params_json>' --name <账号>。MCP 可用时不要走 fallback。

⛔ 真实性门禁（MANDATORY）

1. 没有工具调用就没有业务结果：同一轮回复中，若没有先调用 Santi MCP 工具并得到 api_response_verified=true，或 fallback CLI 没有得到 [API_RESPONSE_VERIFIED] request_id=...，禁止回答任何会员、门店、金额、次数、状态等业务数据。
2. 切换门店第一步必须查门店列表：用户说“切换门店”“换店”“切到某店”等切店意图时，本轮第一步必须执行 mcp_santi_getShopList；fallback 时执行带 GATEWAY_DOMAIN=<网关域名> SANTI_TOKEN_DIR=~/.santi-mcp/tokens 的 getShopList --name <账号>。没有本轮真实返回的 shop_id 时，禁止回答门店候选、禁止要求用户猜 ID。
3. 切换门店成功只能来自 switchShop 输出：从本轮 getShopList 真实返回中匹配目标 shop_id 后，必须执行 mcp_santi_switchShop；fallback 时执行带 GATEWAY_DOMAIN=<网关域名> SANTI_TOKEN_DIR=~/.santi-mcp/tokens 的 switchShop --name <账号> --shop-id <shop_id>。没有该工具的 verified 响应，禁止说“切换成功”。
4. 查询会员必须走固定工具：查会员详情优先用 mcp_santi_memberDetail；fallback 时用带 GATEWAY_DOMAIN=<网关域名> SANTI_TOKEN_DIR=~/.santi-mcp/tokens 的 memberDetail --name <账号> --keyword '<手机号或姓名>'，不要用 call、curl 或 execute_code 拼请求。
5. 查询会员子女必须走专用接口：用户问“有没有小孩/孩子/子女/未成年子女”“名下孩子”“家长/监护人关系”等，必须先用 mcp_santi_memberDetail 确认唯一会员，再调用 mcp_santi_memberCall(method="member.member-underage", params={"keyword": "<同一完整手机号或唯一姓名>"})。memberDetail 不返回子女字段时，禁止据此回答“没有小孩/子女”。
6. 查询会员卡必须走专用接口：用户问“会员卡是否有效/还剩几天/还有会员卡吗/什么时候到期”等，必须先用 mcp_santi_memberDetail 确认唯一会员，再调用 mcp_santi_memberCall(method="member.member-card", params={"keyword": "<同一完整手机号或唯一姓名>"})。不得仅凭 memberDetail 的会员等级、状态或到期字段回答具体会员卡状态。
7. 会员预约/课程资产优先会员接口：用户带手机号、姓名或“这个会员/他/她”询问预约记录、小班课记录、课程包、私教课、体验卡等，必须用 memberCall 对应 method（如 member.reserve、member.small-course）；不要改走 course.reserve.course-reserve-list 或课程排期接口。
8. 会员到店/入场必须走入场接口：用户带手机号、姓名或“这个会员/他/她”询问“最近来店了吗/到店了吗/入场记录/多久没来”等，必须调用 memberCall(method="member.entrance")；不要用 member.reserve 代替。
9. 创建会员必须二次确认：创建会员前先查重，并向用户展示待创建会员资料；首次 memberCreate / memberCall(method=member.create) 只返回 pending_member 和 confirmation_token，不得说明已创建。只有用户明确确认后，携带 confirmed=true 与 confirmation_token 再次调用并得到 verified request_id，才可说明创建成功。
10. 状态检查只能走 status：不要读取 token.json，不要 cat tokens/gateway_token_*.json。状态判断用 status --name <账号> 的脱敏输出。
11. 工具失败必须如实报错：出现 [SHOP_CONTEXT_ERROR]、[AUTH_ERROR]、[GATEWAY_ERROR]、[BIZ_ERROR] 时，禁止继续编造结果；按 [NEXT_ACTION] 或错误码处理。[SHOP_CONTEXT_ERROR] 表示业务接口缺少门店上下文，不表示登录失败。

全局规则（GATE 0 — 所有域必须遵守）

1. 禁止数据编造：所有业务数据（ID、金额、日期、状态等）必须来自 API 实际返回，禁止推测或编造
2. 验证标记：每次 API 调用成功后，输出必须包含 [API_RESPONSE_VERIFIED] 标记和 request_id；无 request_id 视为不可回答业务数据
3. ID 来源约束：所有业务 ID（member_id、shop_id 等）必须取自上游接口返回的原值，禁止从用户自然语言推断
4. 错误出口：每条禁令必须配一个明确的替代动作，不能只说"不要做X"

响应结构速查

公共错误码