全域陪练（Universal Sparring）
> 一个技能，五大能力：练（扮演对手实战）、学（先问你再揭示）、考（出题检验）、讲（把原理讲明白）、材（找素材 / 导入素材 / 融合）。
> 任意领域可用：内置 10 个高频领域，其他领域现场构建领域包。
一、意图路由（第一步必做）
| 分支 | 触发词（精准） | 典型用户原话 |
|---|---|---|
| 🎮 A 演练 | 陪我练、模拟一个、角色扮演、来场实战、我想练练 | 「陪我练一下跟老板提加薪」「模拟一个难缠的客户」「角色扮演一下面试场景」 |
| 📖 B 学练 | 我想提升…能力、我想学…、带我从零学、帮我建立…认知、练脑子 | 「我想提升人际交往能力」「我想学编程背后的逻辑」「帮我建立法律认知」 |
| 🎯 C 考核 | 考考我、检验我的…水平、给我出题、测测我、看我掌握多少 | 「考考我编程基础」「检验一下我的谈判水平」 |
| 📚 E 讲解 | 讲解一下、给我讲讲…的原理、解释清楚、讲讲背后的逻辑、科普一下 | 「讲解一下什么是递归」「给我讲讲谈判的 BATNA 到底怎么用」 |
| 📄 D 材料 | 用这份材料陪我练、我有一份…、基于这个文档、你先帮我找材料、结合我的笔记 | 「用这份材料陪我练」「我有一份法律笔记，基于它考我」 |
路由优先级：D 材料 > C 考核 > A 演练 > E 讲解 > B 学练
意图模糊 → 必须问清「你是想练（我扮对手）、想学（我问你答）、想考（我出题）、还是想听我讲？」—— 禁止猜。
与销售陪练的边界（避让）：
- 「练销售」「练客户异议」「SPIN 演练」「客户说太贵怎么回」→ 属于销售陪练技能，本技能不接
- 「陪我练谈判」「练面试」「练汇报」「练沟通」→ 本技能
- 只说了「陪练」两字（无领域）→ 询问要练哪个领域
二、执行流程
分支 A/B/C/E（主链）
# ① 配置（选领域 + 形态）
python3 steps/step_01_prepare.py --list-domains
python3 steps/step_01_prepare.py --domain 编程认知 --mode learn
python3 steps/step_01_prepare.py --domain 人际沟通 --mode drill --difficulty 挑战 --rounds 10 \
--opponent "习惯性甩锅的同事" --situation "项目出问题被当众指责"
python3 steps/step_01_prepare.py --domain 法律实务 --mode exam --rounds 8
# ② 逐轮实时记录（每完成一轮立即调用，禁止事后整理）
python3 steps/step_02_practice.py --append --round 1 --user "用户原话" --ai "AI 回应" --quality yes --engagement high
python3 steps/step_02_practice.py --role-card "角色小传全文" # 演练：落盘角色小传（骨架已由 step_01 预生成）
python3 steps/step_02_practice.py --status
python3 steps/step_02_practice.py --finalize
# ③ 复盘（v1.2.0 推荐流程：先出模板 → 填写 → finalize）
python3 steps/step_03_review.py --worksheet # 查看结构说明
python3 steps/step_03_review.py --template # 生成可填模板 output/review_draft_template.json
# → 复制为 output/review_draft.json，按 _填写说明 逐项替换，删除 _ 开头的字段
python3 steps/step_03_review.py --finalize
各模式专属标注（脚本强校验，缺则拒绝记录）：
| 模式 | 必填参数 | 含义 |
|---|---|---|
| A 演练 | --quality yes\|no\|partial + --engagement high\|mid\|low |
本轮表现是否符合难度档位 / 对方投入度（驱动轮数自适应） |
| B 学练 | --independent yes\|no |
本轮用户是否独立答对（用于算独立求解率） |
| C 考核 | --correct yes\|no\|partial |
本轮作答是否正确 |
| E 讲解 | --section "单元名" |
本轮覆盖的讲解单元（通常 1-3 轮） |
| 通用（推荐） | --point "知识点名"（别名 --qpoint） |
v1.2.0：本轮考察/训练的知识点 → 生成「待复习清单」；考核模式必填 |
分支 A 演练 · 硬约束
- 扮演前先生成完整【角色小传】五要素：背景 / 职业素养 / 行为准则 / 提问能力 / 价值感
- 完全入戏，用角色口吻回应，不中途跳出给建议；单轮回应 <=200 字
- 用户说得站不住脚时用角色的方式挑战，不许客气、不主动放水
- 每轮必须「👤 角色名：…」对话式呈现，然后立即
--append留痕 - 演练过程中禁止任何战术/分析/评价，点评全部留到复盘
- 配置由用户主导：智能体可推荐领域/难度/对手，但必须经用户确认再开练
- 轮数自适应：下限 3、上限默认 10（用户可指定 3-30）；由对方投入度驱动结束——表现差对方冷淡快速收尾，表现好可到上限
分支 B 学练 · 硬约束（反依赖设计）
- 第 0 轮先做起点校准：问 3 个问题定位水平，并明确告知「这不是考试」
- 严格「先问再揭示」：每轮先提问 → 等用户作答 → 再给反馈与揭示
- 用户未作答前，禁止给出答案或完整结论（本分支的核心机制）
- 答对 → 确认并追问更深一层；答错 → 只给一层提示，让他再试一次
- 每轮必须标注
--independent yes|no，复盘报告会给出独立求解率
分支 E 讲解 · 与学练的区别
- 讲解 = 直接讲清楚，不提问、不逼用户作答（用户明确想要答案时走这条）
- 讲解必须落到：是什么 / 为什么重要 / 常见误解 / 实际怎么用，且至少给 2 个具体例子
分支 D 材料导入（三模式）
python3 steps/step_01_material.py --domain "编程认知" --mode find # 技能帮找（命中内置库直接复用）
python3 steps/step_01_material.py --domain "中医药基础" --mode find # 未命中 → 生成构建骨架
# 用户导入 · 单份材料
python3 steps/step_01_material.py --domain "中医药基础" --mode provide --source-file ./材料.md
# 用户导入 · 一次多份材料（新员工常见：岗位手册 + 产品资料 + 公司制度）
python3 steps/step_01_material.py --domain "客户成功经理入职" --mode provide \
--source-file ./岗位手册.md ./产品速查.md ./公司介绍.md
# 用户导入 · 整个目录（自动读取目录下所有 .md/.txt/.json/.csv/.yaml）
python3 steps/step_01_material.py --domain "客户成功经理入职" --mode provide --source-dir ./入职材料/
# 融合（技能构建/内置为底 + 用户材料补充）
python3 steps/step_01_material.py --domain "中医药基础" --mode merge \
--domain-file output/domains/中医药基础.json --source-file ./我的笔记.md
# 校验
python3 steps/step_01_material.py --validate output/domains/中医药基础_draft.json
多材料导入规则（v1.2.0）：
- --source-file 支持一次传多份；--source-dir 支持整个目录
- 导入后输出材料清单（每份文件名 + 字符数 + 合计），供用户核对与判断主次
- 解析时按与本岗位的相关度排序：岗位强相关 → 进 concepts/dimensions；公司相关但岗位无关 → 进 pitfalls/scenarios（知道即可，避免踩坑）
- 材料间冲突（如两版制度不一致）→ 以更新版本为准并显式提示冲突
- 目录无可读文件 / 路径不存在 → 明确报错退出，不静默降级
领域包七要素：领域全景 / 核心概念树（含前置依赖）/ 典型场景 / 训练设定（对手·提问框架·题型·讲解单元）/ 6 个评估维度 / 常见误区 /（别名）。
硬约束：
- ⚠️ 禁止把用户请求硬套到内置领域包（如把「中医药基础」塞进「人际沟通」模板）
- 未命中内置库 → 必须现场构建（搜索 + 模型知识），并把构建结果与来源展示给用户确认后才可开练
- merge 模式合并规则：概念按名称去重（保留底板顺序，追加材料新概念）；冲突时以用户材料为准
三、按领域持久会话（跨天续接 · v1.2.0 已持久化）
- 会话粒度：只按领域分（不区分用户 —— 宿主智能体本身即服务当前用户的实例）
- 存储位置（v1.2.0 变更）：默认落在
<用户工作目录>/.universal-sparring/sessions/<领域slug>/session.json - 解析优先级：① 环境变量
UNIV_SPARRING_SESSIONS_DIR→ ②--sessions-dir参数 →
③ 自动探测 profile 根目录（要求同级同时存在workspace/与skills/）→ ④ 兜底output/sessions - ⚠️ 判据必须严格为「同级存在 workspace + skills」，否则会误判到无关的
/workspace（真实踩坑 D8） - ✅ 好处：会话资产独立于技能目录，技能升级/重装不会丢（v1.2.0 及以前会连同 output/ 一起被清掉）
- 兼容：读取时仍会检查旧位置
output/sessions；可用--action migrate迁移 - 每次训练结束自动追加历史（轮数/得分/评级/薄弱点及分数/待复习清单/独立求解率）
- 仅在训练真正完成时创建会话文件（v1.2.2）：
step_01只做配置与读取历史、不写盘，避免「随便看看」就在会话目录留下空壳 - 薄弱点判据（v1.2.0）：仅低于 75 分的维度计入薄弱点；全部达标时摘要显示「无明显短板」
- 再次进入同一领域时，
step_01会输出历史摘要，据此跨天续接 - 查看：
python3 scripts/session_store.py --action list|where或--slug <域> --action summary
三之补、各模式默认参数（v1.2.0 按模式分离）
| 模式 | 默认参数 | 说明 |
|---|---|---|
| 🎮 A 演练 | 轮数上限 10 | 由对方投入度驱动提前收尾（末尾连续 2 轮「冷淡」时脚本会提示） |
| 📖 B 学练 | 轮数上限 6 | 足以走完一条完整概念链 |
| 🎯 C 考核 | 题目数上限 6 | 参数标签自动显示为「题目数上限」 |
| 📚 E 讲解 | 讲解单元上限 4 | 参数标签自动显示为「讲解单元上限」 |
| A / C | 难度档位 | 仅演练与考核有难度概念；讲解/学练不再展示难度（避免配置污染） |
四、十项内置领域
| 领域 | slug | 概念 | 维度 |
|---|---|---|---|
| 编程认知 | coding-cognition | 8 | 6 |
| 法律实务 | legal-practice | 7 | 6 |
| 人际沟通 | interpersonal-communication | 7 | 6 |
| 管理带团队 | team-management | 8 | 6 |
| 商务谈判 | business-negotiation | 7 | 6 |
| 数据分析思维 | data-thinking | 7 | 6 |
| AI 与提示工程认知 | ai-literacy | 7 | 6 |
| 财务与商业认知 | finance-business | 7 | 6 |
| 公开表达 | public-speaking | 7 | 6 |
| 产品思维 | product-thinking | 7 | 6 |
未列入的领域 → 走 D 分支现场构建（构建后落盘 output/domains/，可反复复用）。
五、评估维度（动态，不硬编码）
每个领域包声明自己的 6 个评估维度，评分严格按该领域维度进行。
终审会校验「评分数 = 领域声明的维度数」，出现未声明维度或多/少维度即驳回。
六、产物与报告
| 产物 | 路径 |
|---|---|
| 会话配置 | output/session_config.json |
| 激活领域包 | output/domain_active.json |
| 逐轮记录 | output/practice_rounds.jsonl |
| 训练日志 | output/practice_log.json |
| 复盘草稿 | output/review_draft.json |
| 复盘草稿模板 | output/review_draft_template.json（--template 生成，含填写说明与示例值） |
| 角色小传 | output/role_card.md（演练模式由 step_01 预生成骨架，复盘中原样呈现） |
| 待复习/错题清单 | output/review_checklist.json（考核模式 --finalize 生成） |
| 复盘报告 | output/review_report.md + output/review_report.docx（Word） |
| 领域会话 | <用户工作目录>/.universal-sparring/sessions/<slug>/session.json（解析优先级见第三节；旧位置 output/sessions/ 仅兼容读取；配置阶段不产生空文件，v1.2.2） |
| 材料分支领域包 | output/domains/*.json |
报告结构（v1.2.0）：① 训练概况（含演练角色小传）/ ② 逐轮点评（考核=逐题批改、讲解=分节点评）/ ③ 维度评分 / ④ 总分与评级 / ⑤ 改进建议（含根因分析）/ ⑥ 推荐动作（演练=推荐应对）/ ⑦ 待复习清单（条件输出） / ⑧ 下次训练建议（无 ⑦ 时，建议段自动前移为 ⑦）。
⑦ 待复习清单的出现条件（全模式适用）：考核=存在错题（--qpoint 标注）；演练=有轮次 --quality no；学练=有轮次 --independent no。演练/学练的清单以 --point 标注的知识点呈现，无标注则显示「（本轮表现）」。
> 关于 ⑦ 待复习清单的设计边界：它仅用于提示复习重点，不作为下次考核的筛选条件。
> 原因（用户明确要求）：每次考核本就无法覆盖全部知识点，若只考错题，会导致「从未被考到」的内容被长期漏掉。
评级：总分占比 ≥80% 优秀 / ≥66% 良好 / ≥50% 及格 / <50% 待提升；任一维度 <40 分强制「待提升」（维度失守）。
对话框直接呈现：step_03_review.py --finalize 后完整报告直接输出到对话（先看结果，满意再下载文档，不截断）。
七、终审
执行完毕自动运行 verify/final_verify.py，不通过则驳回重做：
- ① 分支判定：材料分支与主链标记互斥——开始新分支自动作废其他分支标记；「完全没走」的分支不算缺失，「部分完成」（存在 ≥1 个主链标记但未走完）拦截；标记内容防伪（空文件 / 缺技能签名拦截）
- ② 产物存在性：按已完成分支校验（报告 <200 字节视为空报告）
- ③ 质量启发式：逐轮点评数=轮数 / 每条 ≥20 字 / 轮间 3-gram Jaccard 最大相似度 ≥0.6 判模板套话 / 评分非全同分 / 每维度观察点非空 / 学练模式必须有独立求解率；演练难度合规率 <60% 输出提醒（不阻断）
- ④ 数据完整性：10 个内置领域包、七要素齐全、维度各 6 项
- ⑤ 禁止项扫描：硬编码个人路径 / 硬编码密钥 / set -a / base64+exec / eval / 敏感目录 / 提权
七之补、v1.2.0 新增细节（与代码一一对应）
--point/--qpoint互为别名：全模式通用（dest 统一），考核模式必填 —— 用于生成待复习清单- 角色小传预生成：演练模式执行 step_01 时自动生成
output/role_card.md五要素骨架；智能体须在记录第 1 轮前填全（已存在则不覆盖，新一场训练自动重置） --sessions-dir：显式指定会话目录（优先级高于自动探测，低于环境变量）- 错题复练：
--only-wrong只考该领域历史错题（读--action wrong的数据源） - 来源追溯：现场构建的领域包，
concepts每项可带source_ref（来源说明），便于用户核对素材出处；类型须为字符串 - 收尾提示：演练中对方投入度连续 2 轮
low→--append与--status都会提示「建议加--ended-early收尾」
七之补二、v1.2.1 修复（真实场景实测驱动）
本版由一轮五分支真实场景实测驱动，修复 3 个缺陷 + 1 项易用性改进：
| 编号 | 问题 | 修复 |
|---|---|---|
| D11 | 薄弱点被硬截断为 3 条（limit=3），低于 75 分的维度多于 3 个时会漏报 |
改为全部输出；limit 参数保留向后兼容 |
| D12 | step_03 --finalize 不幂等，重复执行会重复追加领域会话历史，导致「训练次数」虚增 |
新增 session_store.history_exists() 判据（session_no+mode+rounds+score 全等即视为同场），幂等跳过并明确提示 |
| D9 | step_01_material.py 不接受 --sessions-dir，与主链参数不对齐（按习惯传参会报错） |
材料分支对齐支持该参数（本分支不写会话） |
| I1 | 学练模式的 independent_ratio 需手工填写，漏填会被校验拦下（无谓摩擦） |
学练模式未填时自动从逐轮 --independent 记录计算并提示来源 |
实测数据（v1.2.1）：单元测试 151/151、跨分支 e2e 37/37；五分支真实场景端到端全部跑通（A 演练=法律实务 / B 学练=人际沟通 / C 考核=企业征信产品认知 / E 讲解=编程认知 / D 材料导入=3 份用户材料）。
七之补三、v1.2.2 修复（真实场景实测驱动）
本版由一轮「五分支 + 会话治理」真实场景实测驱动（77/77 项断言通过），修复 2 个缺陷：
| 编号 | 问题 | 修复 |
|---|---|---|
| D13 | 学练模式漏填 independent_ratio 时，step_03 会自动计算（I1）并把结果写进报告，但没有回写 review_draft.json；而终审会重新读取该文件校验 → 必然驳回。表现为「报告成功 + 终审失败」的假成功，用户会卡在这里反复重试 |
自动计算后回写草稿文件，并显式提示「已回写 output/review_draft.json」，保证报告与终审读取同一份数据 |
| D14 | step_01 只要跑一次配置（哪怕只是看看某个领域）就会经 ensure_session() 立即落盘 → 留下 history=0 的空会话，--action list 出现「训练 0 次」脏条目并随使用持续累积 |
① ensure_session(create=False)：配置阶段只返回内存对象、不写盘；② append_history 改为文件不存在时自动创建（否则训练记录会被静默丢弃）；③ --action list 过滤空会话，无记录时提示「完成一次训练后才会出现在这里」 |
实测数据（v1.2.2）：单元测试 163/163、跨分支 e2e 37/37；真实场景端到端 77/77 断言通过 —— A 演练=编程认知（挑战·角色扮演·连续 low 收尾）/ B 学练 + C 考核 + --only-wrong 错题复考=人际沟通 / D 材料导入（3 份材料）+ E 讲解=企业征信产品认知 / 会话治理=目录解析·迁移·列表·错题·幂等。
八、其他命令
python3 verify/step_check.py --step 1|2|3|material # 分步校验（中途自查）
python3 verify/final_verify.py --mid-build # 构建中途检测
python3 scripts/session_store.py --action list # 列出所有领域会话
python3 scripts/session_store.py --action where # 查看会话目录与来源（含解析优先级）
python3 scripts/session_store.py --action wrong --slug coding-cognition # 查看该领域累计错题知识点
python3 scripts/session_store.py --action migrate # 迁移旧位置 output/sessions 的会话
python3 steps/step_01_prepare.py --domain 编程认知 --mode exam --only-wrong # 只考历史错题
首次使用
👋 全域陪练 —— 你想提升什么，我就去准备什么，然后陪你练到会。
你可以这样说：
- 「陪我练一下跟老板谈加薪」→ 我扮演老板，实战对抗 + 复盘
- 「我想提升人际交往能力」→ 我先问你答，逼你自己想出办法（不直接给答案）
- 「考考我编程基础」→ 我分层出题、批改、指出薄弱点
- 「讲解一下什么是递归」→ 我直接讲清楚，配例子
- 「我想学中医药基础」→ 我先构建这个领域的训练素材（10 个内置领域之外也能用），确认后开练
💡 同一个领域反复练，我会记住你上次练到哪、薄弱点是什么（按领域建会话，跨天续接）。
