acmer-coach 1.0.0

package/coach/analyze_map.py

@@ -0,0 +1,138 @@
+#!/usr/bin/env python3
+"""
+analyze_map.py — 看地图的拓扑形状：环 / 深度 / 最长链 / 未铺进度
+
+跟 validate_map.py 的分工：
+  validate_map.py  管「结构合不合法」（环、孤儿边、重复 id、引用）
+  analyze_map.py   管「形状对不对」（深度分布、最长链、铺了多少）
+
+用法: python analyze_map.py
+"""
+import os
+import sys
+from collections import Counter, defaultdict
+
+import yaml
+
+for _s in (sys.stdout, sys.stderr):
+    if _s and hasattr(_s, "reconfigure"):
+        _s.reconfigure(encoding="utf-8", errors="replace")
+
+MAP = os.path.join(os.path.expanduser("~"), ".dsh", "knowledge", "MAP.yaml")
+
+
+def main():
+    doc = yaml.safe_load(open(MAP, encoding="utf-8"))
+    nodes = doc["nodes"]
+    name_of = {n["id"]: n["name"] for n in nodes}
+    dom = {n["id"]: n["domain"] for n in nodes}
+
+    # 只认已铺的边：depends 为 None = 还没铺
+    dep = {}
+    for n in nodes:
+        if n.get("depends") is None:
+            dep[n["id"]] = None                      # 未铺
+        else:
+            dep[n["id"]] = [d for d in n["depends"] if d in name_of]
+
+    covered = [k for k, v in dep.items() if v is not None]
+    pending = [k for k, v in dep.items() if v is None]
+
+    print("=" * 62)
+    print(f"节点 {len(nodes)}   已铺前置 {len(covered)}   未铺 {len(pending)}")
+    print("=" * 62)
+
+    # ── 环检测（未铺的节点不参与）──
+    WHITE, GREY, BLACK = 0, 1, 2
+    color = defaultdict(int)
+    cycles = []
+
+    def dfs(u, path):
+        color[u] = GREY
+        for v in dep.get(u) or []:
+            if dep.get(v) is None:
+                continue
+            if color[v] == GREY:
+                i = path.index(v)
+                cycles.append(path[i:] + [v])
+            elif color[v] == WHITE:
+                dfs(v, path + [v])
+        color[u] = BLACK
+
+    for u in covered:
+        if color[u] == WHITE and dep.get(u) is not None:
+            dfs(u, [u])
+
+    if cycles:
+        print(f"❌ 发现 {len(cycles)} 个环：")
+        for c in cycles[:5]:
+            print("   " + " → ".join(name_of.get(x, x) for x in c))
+        return 1
+    print("✅ 无环\n")
+
+    # ── 最长路分层 ──
+    # 关键：祖先链上只要还有一个「未铺」的节点，这个节点的深度就是**未知**，
+    # 不是 0。把"不知道"当成"根"会让整张图看起来比实际浅得多 —— 前面吃过这个亏。
+    memo = {}
+    _stack = set()
+
+    def depth(u):
+        """层深；祖先链上有未铺节点 → None（未知）。"""
+        if u in memo:
+            return memo[u]
+        if u in _stack:                 # 防御：理论上无环，已在上游校验
+            return 0
+        ps = dep.get(u) or []
+        if any(dep.get(p) is None for p in ps):
+            memo[u] = None
+            return None
+        _stack.add(u)
+        ds = [depth(p) for p in ps]
+        _stack.discard(u)
+        if any(d is None for d in ds):
+            memo[u] = None
+        else:
+            memo[u] = 0 if not ds else max(ds) + 1
+        return memo[u]
+
+    for u in covered:
+        depth(u)
+
+    known = {u: depth(u) for u in covered if depth(u) is not None}
+    unknown = sorted(set(covered) - set(known))
+    lv = Counter(known.values())
+    print("=== 拓扑深度（只统计祖先链全部已铺的节点）===")
+    mx = max(lv) if lv else 0
+    for k in range(mx + 1):
+        n = lv.get(k, 0)
+        print(f"  L{k:<2} {n:>3} 个  {'█' * min(n, 55)}")
+    print(f"\n  最大深度 {mx} 层（目标 8-12）")
+    print(f"  深度可算的 {len(known)} 个；深度**未知**（祖先链上有未铺）{len(unknown)} 个")
+
+    # ── 最深的三条链 ──
+    def chain(u):
+        ps = dep.get(u) or []
+        if not ps:
+            return [u]
+        return chain(max(ps, key=lambda p: known.get(p, -1))) + [u]
+
+    print("\n=== 最深的三条链 ===")
+    for u in sorted(known, key=known.get, reverse=True)[:3]:
+        ch = chain(u)
+        print(f"  ({len(ch) - 1} 层) " + " → ".join(name_of.get(x, x) for x in ch))
+
+    # ── 未铺进度 ──
+    if pending:
+        print(f"\n=== 未铺前置的 {len(pending)} 个（按学科）===")
+        for d, c in Counter(dom[k] for k in pending).most_common():
+            print(f"  {d:<8} {c:>3}")
+
+    # ── 根节点（确认不需要前置的）──
+    roots = [k for k in covered if not dep[k]]
+    print(f"\n=== 确认的根节点 {len(roots)} 个 ===")
+    print("  " + " / ".join(sorted(name_of.get(r, r) for r in roots)))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/coach/build_map.py

@@ -0,0 +1,230 @@
+#!/usr/bin/env python3
+"""
+build_map.py — 用 OI-wiki 全量条目 + DEPENDS.yaml，生成 MAP.yaml
+
+设计（第三版）：
+  前两版都错在同一处：**把 OI-wiki 的 parent 当成了前置。**
+
+  parent 是「分类归属」（树链剖分和树分治放在"树上问题"下面一起讲），
+  requires 是「前置」（不会 DFS 就学不了树链剖分）。这两个关系在 OI-wiki
+  的目录里长得一模一样，但完全不是一回事：
+    - 「树上问题」是抽屉，不是知识点 —— 你不可能"掌握树上问题"
+    - 「李超线段树」和「线段树」在目录里同级，但后者是前者的前置
+
+  第二版因为「同域内的树形关系不写」，把同域内的真实前置全丢了
+  （素数→筛法→莫比乌斯反演 这些边从来没被记过），
+  351 个点里 230 个没有前置，拓扑深度只有 3 层。
+
+  这一版：
+    - 前置关系全部来自 knowledge/DEPENDS.yaml（数据，不是代码）
+    - **每个节点显式写全部直接前置**，不靠 parent 顶替
+    - parent 降级为纯分组字段，只用于显示，不参与任何依赖计算
+
+  每个节点留 `tier` 字段（core/normal/rare/skip）—— 本版**先留空**，
+  等第 2 遍叠权重/难度时一起标。先求全，再求挑。
+
+用法: python build_map.py   → 覆写 ~/.dsh/knowledge/MAP.yaml
+"""
+import json
+import os
+import sys
+from collections import Counter
+
+import yaml
+
+for _s in (sys.stdout, sys.stderr):
+    if _s and hasattr(_s, "reconfigure"):
+        _s.reconfigure(encoding="utf-8", errors="replace")
+
+HERE = os.path.dirname(os.path.abspath(__file__))
+SRC = os.path.join(HERE, "oiwiki_tree.json")
+DEPS = os.path.join(os.path.expanduser("~"), ".dsh", "knowledge", "DEPENDS.yaml")
+META = os.path.join(os.path.expanduser("~"), ".dsh", "knowledge", "NODE_META.yaml")
+ENTRY = os.path.join(os.path.expanduser("~"), ".dsh", "knowledge", "NODE_ENTRY.yaml")
+OUT = os.path.join(os.path.expanduser("~"), ".dsh", "knowledge", "MAP.yaml")
+
+# 平行分支（不是依赖，是「选一条走即可」）
+PARALLEL_HINTS = [
+    {"a": "树状数组", "b": "线段树", "note": "区间维护的两条独立路线，走通一条即可"},
+    {"a": "块状数据结构", "b": "线段树", "note": "分块是线段树的朴素退路，学不动时可先走分块"},
+    {"a": "Treap", "b": "Splay 树", "note": "平衡树任选一种写熟即可，另一种按需补"},
+    {"a": "后缀数组 (SA)", "b": "后缀自动机 (SAM)", "note": "字符串难题的两条路线，先走通一条"},
+    {"a": "单调队列/单调栈优化", "b": "线段树", "note": "都是优化 DP 转移的手段"},
+]
+
+
+def slug(name):
+    """id 直接用中文全名 —— 自解释、可读、不必维护映射表。"""
+    return name
+
+
+def load_requires():
+    """读 DEPENDS.yaml → ({节点名: [直接前置]}, 文档头)。
+
+    返回的字典里**没有**的节点 = 前置还没铺（不是"根节点"）。
+    这个区别很重要：没铺是"不知道"，空列表是"确认不需要前置"。
+    """
+    if not os.path.exists(DEPS):
+        print(f"❌ 找不到 {DEPS}")
+        return None, None
+    doc = yaml.safe_load(open(DEPS, encoding="utf-8")) or {}
+    return (doc.get("requires") or {}), (doc.get("meta") or {})
+
+
+def load_meta():
+    """读两份**标注**（都不是地图结构，是"这知识点重不重要 / 什么水平学得起"）。
+
+    NODE_META.yaml   人维护 —— tier（core/normal/rare/skip）+ 偏离默认时的依据
+    NODE_ENTRY.yaml  机器算 —— entry（题池的 p25）+ pool/median，见 build-node-meta.mjs
+
+    两份分开是有意的：机器那份可以**全权重写**，人那份**谁都不许动**。
+    混在一个文件里，"脚本重跑"和"人改标注"就会互相冲掉 ——
+    跟 PROGRESS.yaml 的 yaml 库吃注释是同一个坑。
+    """
+    tiers, entries = {}, {}
+    if os.path.exists(META):
+        doc = yaml.safe_load(open(META, encoding="utf-8")) or {}
+        tiers = doc.get("nodes") or {}
+    if os.path.exists(ENTRY):
+        doc = yaml.safe_load(open(ENTRY, encoding="utf-8")) or {}
+        entries = doc.get("nodes") or {}
+    return tiers, entries
+
+
+def main():
+    items = json.load(open(SRC, encoding="utf-8"))
+    req, dep_meta = load_requires()
+    if req is None:
+        return 1
+    tiers, entries = load_meta()
+
+    # 同一 domain 内重名 → 用 path 前缀消歧
+    seen = Counter((i["domain"], i["name"]) for i in items)
+    dupes = {k for k, v in seen.items() if v > 1}
+
+    nodes = []
+    skipped = []
+    for it in items:
+        name = it["name"]
+        path = it["path"]
+        # OI-wiki 里有些页面既是分组名、又是分组里的条目（并查集 / 二叉搜索树 & 平衡树），
+        # 抽出来会变成 X 和 X/X 两个节点、指向同一个知识点 —— 丢掉自嵌套的那个，
+        # 否则图上会出现两个一模一样的点。
+        if len(path) == 2 and path[0] == path[1] == name:
+            skipped.append(name)
+            continue
+        parent = path[0] if len(path) > 1 else None
+        nid = name
+        if (it["domain"], name) in dupes:
+            nid = "/".join(path)
+        nodes.append({
+            "id": nid,
+            "name": name,
+            "domain": it["domain"],
+            "parent": parent,                          # 仅用于分组显示
+            "depends": req.get(name) if name in req else None,   # None = 前置未铺
+            "tier": (tiers.get(name) or {}).get("tier"),          # NODE_META.yaml
+            "entry": (entries.get(name) or {}).get("entry"),      # NODE_ENTRY.yaml
+            "pool": (entries.get(name) or {}).get("pool"),
+        })
+
+    ids = {n["id"] for n in nodes}
+    names = {n["name"] for n in nodes}
+
+    # 校验：DEPENDS.yaml 里引用的前置必须真实存在
+    bad = []
+    for n in nodes:
+        for d in n["depends"] or []:
+            if d not in names and d not in ids:
+                bad.append(f"{n['name']} → {d}（不存在）")
+
+    covered = sum(1 for n in nodes if n["depends"] is not None)
+    edge_count = sum(len(n["depends"] or []) for n in nodes)
+
+    # ── 输出 YAML（手写序列化，保证可读 + 稳定顺序）──
+    L = []
+    L.append("# ══════════════════════════════════════════════════════════════")
+    L.append("# MAP.yaml — 教练地图 v3（前置 = depends，分类 = parent）")
+    L.append("#")
+    L.append("# 生成方式：coach/build_map.py（OI-wiki 导航 351 条 + knowledge/DEPENDS.yaml）")
+    L.append("#   ⚠️ 不要手改本文件 —— 改 DEPENDS.yaml 再重跑 build_map.py。")
+    L.append("#")
+    L.append("# 结构约定：")
+    L.append("#   depends  前置。学这个之前必须先掌握的直接前置。空列表 = 确认的根节点，")
+    L.append("#            null = 还没铺（**不是根，是不知道**，别把它排到最前面）。")
+    L.append("#   parent   分类归属，**只用于分组显示，不是前置**。")
+    L.append("#            「树上问题」是抽屉不是知识点 —— 它不参与任何依赖计算。")
+    L.append("#   tier     这个知识点重不重要：core/normal/rare/skip。")
+    L.append("#            来自 knowledge/NODE_META.yaml（人手维护），本文件只做合并。")
+    L.append("#   entry    题池的 p25，≈「什么水平开始学得起」。**只有有题池的节点才有**。")
+    L.append("#            来自 knowledge/NODE_ENTRY.yaml（机器算，跑 build-node-meta.mjs）。")
+    L.append("# ══════════════════════════════════════════════════════════════")
+    L.append("")
+    L.append("meta:")
+    L.append("  version: 3")
+    L.append("  source: OI-wiki 导航（mkdocs.yml）")
+    L.append(f"  node_count: {len(nodes)}")
+    L.append(f"  edge_count: {edge_count}")
+    L.append(f"  depends_covered: {covered}/{len(nodes)}")
+    L.append("")
+    L.append("nodes:")
+
+    cur_domain = None
+    for n in sorted(nodes, key=lambda x: (x["domain"], x["parent"] or "", x["name"])):
+        if n["domain"] != cur_domain:
+            cur_domain = n["domain"]
+            L.append(f"  # ── {cur_domain} ──")
+        L.append(f"  - id: {n['id']}")
+        L.append(f"    name: {n['name']}")
+        L.append(f"    domain: {n['domain']}")
+        if n["parent"]:
+            L.append(f"    parent: {n['parent']}")
+        if n["depends"] is not None:
+            L.append(f"    depends: [{', '.join(n['depends'])}]")
+        # tier / entry 是**标注**，不是地图结构 —— 来自 NODE_META.yaml 和
+        # NODE_ENTRY.yaml，本文件只负责合并。缺了就不写这一行（缺 = 没标 / 没数据）。
+        if n["tier"]:
+            L.append(f"    tier: {n['tier']}")
+        if n["entry"]:
+            L.append(f"    entry: {n['entry']}      # 题池 p25（≈入门段位），机器算")
+        if n["pool"]:
+            L.append(f"    pool: {n['pool']}        # entry 是拿这么多道题算出来的")
+        L.append("")
+
+    L.append("parallel_branches:")
+    for p in PARALLEL_HINTS:
+        L.append(f"  - a: {p['a']}")
+        L.append(f"    b: {p['b']}")
+        L.append(f"    note: {p['note']}")
+    L.append("")
+
+    with open(OUT, "w", encoding="utf-8") as f:
+        f.write("\n".join(L))
+
+    by_domain = Counter(n["domain"] for n in nodes)
+    print(f"生成完成 → {OUT}")
+    print(f"  节点 {len(nodes)}   前置边 {edge_count}   已铺前置 {covered}/{len(nodes)}")
+    # 标注覆盖率要报出来。静默漏标 = 教练拿到一个没有 tier 的节点、
+    # 悄悄按"没标注"处理，而人以为标全了 —— 又一种"盘上少了一块没人知道"。
+    no_tier = [n["name"] for n in nodes if not n["tier"]]
+    no_entry = [n["name"] for n in nodes if not n["entry"]]
+    print(f"  已标 tier {len(nodes) - len(no_tier)}/{len(nodes)}"
+          f"   有入门段位 {len(nodes) - len(no_entry)}/{len(nodes)}")
+    if no_tier:
+        head = " / ".join(no_tier[:8])
+        print(f"  ⚠️ 没标 tier 的 {len(no_tier)} 个：{head}{' …' if len(no_tier) > 8 else ''}")
+    if skipped:
+        print(f"  丢弃自嵌套重复节点 {len(skipped)} 个：{' / '.join(skipped)}")
+    for k, v in by_domain.most_common():
+        print(f"    {k:8s} {v:4d}")
+    if bad:
+        print(f"\n❌ {len(bad)} 个引用问题：")
+        for b in bad[:15]:
+            print(f"   - {b}")
+        return 1
+    print("\n✅ 引用完整（DEPENDS.yaml 里的前置都能对上）")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/coach/build_node_pages.py

@@ -0,0 +1,105 @@
+#!/usr/bin/env python3
+"""把「地图节点 → OI Wiki 页面」这张表建出来。
+
+**为什么要它**：地图节点的名字就是从 OI Wiki 导航标题来的，所以
+`节点名 → 文件路径` 是一张**精确表**，不是猜的。有了它，查资料就不用靠
+模糊搜索去撞 —— 搜"线段树"可能撞出一堆相关页，查表只有一页，而且是对的。
+
+**分类节点怎么办**：导航里有一层是纯分类（「网络流」底下挂着最大流 / 费用流…），
+它自己没有页面。这类节点的内容就散在整棵子树里，所以映射到**后代的全部文件**。
+
+⚠️ 两个踩过的坑，决定了这里必须**递归遍历原始树**，不能复用 flatten 的结果：
+  ① 只走三层会漏 —— 「莫队算法」的 8 个子页面在**第四层**，一层都收不到；
+  ② flatten 会按 SKIP_SUFFIX 滤掉「XX 简介」—— 那个过滤是给**地图节点**用的
+     （不该把"线段树简介"当成一个知识点），但**章节页面**不能滤：
+     「后缀数组 (SA)」的两个页面里有一个就叫「后缀数组简介」，滤掉就少收一页。
+
+用法:
+  python build_node_pages.py <map.yaml> <mkdocs.yml> <输出 node-pages.json>
+
+⚠️ 第二个参数要**原始的 mkdocs.yml**，不是 extract_oiwiki.py 拍平后的
+   `oiwiki_tree.json` —— 拍平那份没有 kids，拿它建子树并集会是空的。
+   解析器直接复用 extract_oiwiki.parse_nav，一份实现。
+
+产物: {"节点名": ["相对路径.md", ...]}  —— 路径相对 OI Wiki 的 docs/
+"""
+import json
+import os
+import sys
+
+import yaml
+
+sys.path.insert(0, os.path.dirname(os.path.abspath(__file__)))
+from extract_oiwiki import parse_nav   # noqa: E402  （同目录的解析器，别抄第二份）
+
+
+def descendants(node, acc):
+    """收集一棵子树的全部文件（任意深度，不过滤）。"""
+    for k in node.get("kids", []):
+        if k.get("file"):
+            acc.append(k["file"])
+        descendants(k, acc)
+    return acc
+
+
+def walk(tree):
+    """遍历原始导航树 → {name: [files]}。"""
+    by_name, by_section = {}, {}
+
+    def visit(node):
+        name = node.get("name")
+        if node.get("file"):
+            by_name.setdefault(name, node["file"])
+        sub = descendants(node, [])
+        if sub:
+            by_section.setdefault(name, sub)
+        for k in node.get("kids", []):
+            visit(k)
+
+    for d in tree:
+        visit(d)
+    return by_name, by_section
+
+
+def dedup(xs):
+    seen, acc = set(), []
+    for x in xs:
+        if x not in seen:
+            seen.add(x)
+            acc.append(x)
+    return acc
+
+
+def main():
+    if len(sys.argv) < 4:
+        print(__doc__)
+        return 1
+    map_path, nav_path, out_path = sys.argv[1:4]
+
+    tree = parse_nav(nav_path)
+    nodes = [n["id"] for n in yaml.safe_load(open(map_path, encoding="utf-8"))["nodes"]]
+
+    by_name, by_section = walk(tree)
+
+    out, missing = {}, []
+    for n in nodes:
+        if n in by_name:
+            out[n] = [by_name[n]]              # 有自己页面的，精确到那一页
+        elif n in by_section:
+            out[n] = dedup(by_section[n])      # 分类节点，落到整棵子树的页面
+        else:
+            missing.append(n)
+
+    json.dump(out, open(out_path, "w", encoding="utf-8"),
+              ensure_ascii=False, indent=1)
+
+    multi = sum(1 for v in out.values() if len(v) > 1)
+    print(f"· 映射 {len(out)}/{len(nodes)} 个节点（{multi} 个走子树并集）")
+    if missing:
+        print(f"  ⚠️ 没有页面的 {len(missing)} 个: {missing[:12]}")
+    print(f"  → {out_path}")
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/coach/check_page_syntax.mjs

@@ -0,0 +1,48 @@
+// 语法级体检：把 skilltree.html 里的内联 script 抽出来过一遍 V8 解析。
+//
+// 为什么要它：改模板（CYCLE 数组、键盘映射、图例文字）时最容易的坏法是
+// 把某处语句写坏 —— 那样的页面**照样 HTTP 200**，打开来是一片空白，
+// 而 curl 看不出来。这里只做**解析**，不执行（不碰 DOM）。
+//
+// 用法: node check_page_syntax.mjs [要检查的 html]
+//   不给参数就检查**模板本身**（coach/skilltree_template.html）。
+//   要检查渲染产物就传路径，或用 COACH_DATA_DIR 指到数据目录。
+import { readFileSync } from 'node:fs'
+import { homedir } from 'node:os'
+import { join, dirname } from 'node:path'
+import { fileURLToPath } from 'node:url'
+import vm from 'node:vm'
+
+const HERE = dirname(fileURLToPath(import.meta.url))
+const FILE = process.argv[2]
+  || join(process.env.COACH_DATA_DIR || join(homedir(), '.dsh', 'knowledge'), 'skilltree.html')
+const html = readFileSync(FILE, 'utf8')
+const blocks = [...html.matchAll(/<script(?![^>]*\bsrc=)[^>]*>([\s\S]*?)<\/script>/g)]
+  .map((m) => m[1]).filter((c) => c.trim())
+
+console.log(`skilltree.html：${html.length} 字符，内联 script 块 ${blocks.length} 个`)
+let bad = 0
+blocks.forEach((code, i) => {
+  try {
+    new vm.Script(code, { filename: `inline-${i}.js` })
+    console.log(`  块 ${i}: 语法 OK（${code.length} 字符）`)
+  } catch (e) {
+    bad++
+    console.log(`  块 ${i}: ✗ ${e.message}`)
+  }
+})
+
+// 顺带把这次改动关心的三件事也钉一下（不执行页面，只查文本）
+const asserts = [
+  ['CYCLE 只有三档', /const CYCLE = \["none", "studying", "learned"\]/.test(html)],
+  ['键盘映射是 123', /"123"\.indexOf\(e\.key\)/.test(html)],
+  ['没有残留的 "1234"', !html.includes('"1234"')],
+  ['图例不再说「→ 已验证」循环', !html.includes('未学 → 在学 → 学过 → 已验证')],
+  ['verified 仍留在显示用的 LABEL / COLOR 里', html.includes('verified: "已验证"')],
+]
+console.log('')
+for (const [label, ok] of asserts) {
+  console.log(`  ${ok ? 'OK  ' : 'FAIL'} ${label}`)
+  if (!ok) bad++
+}
+process.exit(bad ? 1 : 0)