校长经营驾驶舱（principal-cockpit）
功能概述
面向教培小机构校长的经营分析 Skill：Excel 进、驾驶舱出、行动建议带走。不改变机构记账习惯，读取现有台账自动计算 20+ 经营指标，对标行业基准（课消率 ≥85%、续班率 ≥75%、现金储备 ≥6 个月等）分红黄绿三档，对每个红黄指标给出归因解读与行动建议，并逐笔扫描预收费合规红线（单笔超 3 个月/60 课时/5000 元）。只做只读分析，不做录入系统、不做支付/催收等执行动作，数据全本地处理。
使用前提
- 运行环境：Python 3.8+（读取 .xlsx 需
pip install openpyxl；纯 CSV 无任何第三方依赖） - 前置数据：至少一张学员课时表（Excel/CSV 均可）；其余收支流水、线索跟进、班级课表、成本费用表可选，缺哪类自动降级哪类域
- 无连接器依赖：不需要任何 API Key 与在线服务；数据不离开本机
- 可选生态联动：若已安装 edu-sales-crm / ar-collector / utm-attribution / order-recon，可直接读取其台账免导入
快速开始
- 对话说"帮我建校长驾驶舱"（或拖入 Excel 台账说"分析经营情况"）；
- 按引导逐张导入台账（只有学员课时表也能出看板），确认列映射；
- 一次性回答基础配置（月固定成本/单课时均价等，可跳过则用估算）；
- 打开生成的 HTML 驾驶舱，按"本周三件事"行动。
> 用户：这是我们学员课时表和收支流水，帮我看看经营情况
> 技能：已识别两张表……确认"剩余课时"是否含赠送课时？……驾驶舱已生成：健康分 45（红 3 黄 3 绿 1），现金储备 0.3 个月红灯，检出 2 笔收费超红线，建议改拆季度缴费。
使用手册
核心功能与操作示例
功能 1：建驾驶舱（冷启动）
- 触发方式："建驾驶舱 / 经营报表 / 机构体检 / 帮我看看经营情况"，或直接拖入台账文件
- 操作示例：
> 用户：建个校长驾驶舱，这是我们机构的表
> 技能：进入引导流程——先检测生态台账，再逐张导入并确认列映射，最后询问基础配置，生成看板并用三句话总结 - 注意事项：列映射置信度低时必须人工确认，宁可多问一句不可猜错；数据异常（空值/负数/坏日期/重复行）会列清单供选择跳过或修正
功能 2：经营问答
- 触发方式："这个月课消率怎么样 / 3 月满班率多少 / 现金还能撑几个月"
- 操作示例：
> 用户：这个月课消率怎么样？
> 技能：57.2%（红灯，基准 ≥85%）· 环比 -12.3pp。主因停课学员占在读 10%（上月 6%），建议优先复课激活。 - 注意事项：所有数值来自最新快照文件，不凭记忆作答；缺数据时明说缺哪张表
功能 3：归因下钻
- 触发方式："为什么 XX 降了 / 现金储备为什么是黄的"
- 操作示例：
> 用户：为什么现金储备是红的？
> 技能：本月实收环比未降，主因支出端课酬/人力合计 5.6 万且 6 月市场投放 3.2 万（环比 +237%）；建议编制 8 周现金流滚动表并冻结非必要支出。 - 注意事项：归因至少下钻一层，禁止只复述指标值
功能 4：预收费合规扫描
- 触发方式："有没有违规收费 / 合规检查"
- 操作示例：
> 用户：查一下有没有违规收费
> 技能：检出 3 笔疑似违规：7-08 周** 6800 元（跨度 12 个月+超 5000 元）等；建议拆分为不超 3 个月/5000 元的分段缴费并走监管专户。以当地主管部门解释为准。 - 注意事项：只提示"疑似违规"不做定性结论，引用教育部等十三部门《意见》
功能 5：流失预警与续费名单
- 触发方式："谁快流失了 / 该续费名单"
- 操作示例：
> 用户：谁快流失了？
> 技能：流失预警 103 人（剩余课时<8 且 30 天未消课 87 人、闲置>45 天 16 人），Top 名单已脱敏，可导出 CSV 交教务逐一回访。 - 注意事项：名单默认脱敏（仅显示姓），导出完整名单前会提示截图外泄风险
功能 6：经营周报
- 触发方式："出周报 / 月度体检报告"
- 操作示例：
> 用户：出周报
> 技能：生成 Markdown 周报：健康分与环比、本周三件事（现金流滚动表/复课激活/名单挽留）、异常解读。 - 注意事项：数据未更新时沿用最近快照并注明日期
功能 7：指标口径解释
- 触发方式："课消率怎么算的 / 续班率口径是什么"
- 操作示例：
> 用户：课消率怎么算的？
> 技能：课消率 = 结转收入 ÷ 同期现金收入，基准 ≥85%（菲特云馆主学院）；贵机构当前为估算口径（按缴费跨度月度摊销），导入消课明细后自动切换精确口径。 - 注意事项：公式与基准出处见 references/metrics-definitions.md
数据说明
工作目录 cockpit-data/（当前 workspace 下自动创建）：
| 路径 | 内容 |
|---|---|
raw/ |
原始导入文件按日期归档（不外传） |
normalized/ |
标准化台账：students.json / cashflow.json / leads.json / classes.json / expenses.json |
snapshots/ |
指标快照 YYYY-MM.json + 预警 _alerts.json + 合规 _compliance.json |
config.json |
列映射记忆、月固定成本、单课时均价、阈值覆盖 |
5 类台账的字段与同义词映射（"剩余课时/还剩几节/课时余额"等 30+ 变体自动识别）见 scripts/importer.py 的 COLUMN_SYNONYMS；指标公式与行业基准见 references/metrics-definitions.md。空白台账模板见 assets/excel-templates/（students/cashflow/leads/classes/expenses 五张 CSV，Excel 可直接编辑）。
常见问题
Q1：打开 .xlsx 报错缺少 openpyxl？
执行 pip install openpyxl；或将 Excel 另存为 CSV 导入（无依赖）。
Q2：只有一张学员表能用吗？
可以。留存域照常计算，财务/招生域显示"数据缺失"，看板仍会生成（健康分按可用域归一化权重）。
Q3：CAC 显示"缺市场费用数据"而不是 0？
设计如此：缺成本表时宁可不算也不给误导性 0 值，导入成本费用表后重算即可。
Q4：现金储备标了"估"是什么意思？
未配置现金余额时按历史流水推算。在 config.json 填 cash_balance 后重算即为精确值。
Q5：看板需要联网吗？
不需要。HTML 单文件自包含（约 15KB），双击即开，可发微信/邮件给合伙人。
Q6：学员隐私怎么处理？
全部计算在本地完成；名单默认脱敏（仅显示姓）；normalized 数据不保留原始行；无任何网络请求。
Q7：Excel 列名很乱能识别吗？
内置 30+ 列同义词；识别不了的会进入人工列映射确认，确认一次后同结构表免配置。
技能指令（开发者参考）
意图路由
| 用户说法 | 流程 |
|---|---|
| 建驾驶舱/经营报表/机构体检 | 冷启动：生态扫描 → 逐表导入确认 → 配置 → 三连命令出看板 |
| 导入数据/更新数据 | importer → metrics → alerts → dashboard 重跑 |
| 出周报/月度体检 | dashboard.py --weekly 基于最新快照 |
| XX率多少/这月XX怎么样 | 读 snapshots 最新 JSON：数值+分档+基准+环比 |
| 为什么XX | 读 _alerts.json 的 attribution 字段回答 |
| 谁快流失了/该续费名单 | 读 retention.churn_risk_list / expiring_list |
| 有没有违规收费 | 读 _compliance.json；无则重扫 normalized/cashflow.json |
| 改阈值/面积/均价 | 更新 config.json 后重算 |
标准命令链
python scripts/importer.py --detect <file> # 先识别
python scripts/importer.py --import <file> --type students --data-dir cockpit-data
python scripts/metrics.py --data-dir cockpit-data --month <YYYY-MM>
python scripts/alerts.py --snapshot cockpit-data/snapshots/<YYYY-MM>.json --config cockpit-data/config.json
python scripts/dashboard.py --snapshot cockpit-data/snapshots/<YYYY-MM>.json --alerts cockpit-data/snapshots/<YYYY-MM>_alerts.json --out cockpit-data/dashboard_<YYYY-MM>.html
对话规范与红线
- 指标回答固定格式：数值（红/黄/绿灯，基准 X）· 环比 Y%；数据缺失明说缺什么
- 生态台账只读（importer.py --eco 扫描），不重复建设兄弟 skill 的功能
- 合规只提示"疑似违规"+政策出处，不做定性；看板页脚固定免责声明
- 学员姓名默认脱敏；不给"必须"式建议，用"建议考虑"
- 不做：录入系统/签到消课、支付/催收/外呼、多校区合并（V2）、外部 SaaS API 同步
降级策略
| 缺失 | 行为 |
|---|---|
| 仅学员表 | 看板仍生成，缺域标注"数据缺失"，健康分权重归一化 |
| 无费用表 | CAC 显示"缺数据"非 0 |
| 无现金配置 | 储备按流水推算标"估" |
| 无容量列 | 满班率隐藏不显示 0 |
| 无试听环节 | 漏斗降三级并注明 |
脚本清单
| 脚本 | 职责 |
|---|---|
| scripts/importer.py | 5 类表识别（关键词打分）、列同义词映射、校验、生态台账扫描 |
| scripts/metrics.py | 20+ 指标纯函数计算，输出快照 |
| scripts/alerts.py | 分档/归因/建议/合规扫描/健康分 |
| scripts/dashboard.py | 自包含 HTML 看板与 Markdown 周报 |
| references/metrics-definitions.md | 指标公式、行业基准与数据来源 |
| assets/excel-templates/ | 5 类空白台账模板 |
