fix: harden tool-list, dashboard, and CI after code review

Fix tool-list logic bugs, unify Chinese docstrings, add pytest/ruff CI,
harden dashboard PATCH handling, and remove tracked compile artifacts.

Author: fooSynaptic

.editorconfig

@@ -0,0 +1,22 @@
+root = true
+
+[*]
+charset = utf-8
+end_of_line = lf
+insert_final_newline = true
+trim_trailing_whitespace = true
+indent_style = space
+indent_size = 4
+
+[*.{md,markdown}]
+trim_trailing_whitespace = false
+
+[*.{yaml,yml}]
+indent_size = 2
+
+[*.{c,cpp,h}]
+indent_style = tab
+indent_size = 4
+
+[Makefile]
+indent_style = tab

.github/workflows/ci.yml

@@ -0,0 +1,64 @@
+name: CI
+
+on:
+  push:
+    branches: [master, main]
+  pull_request:
+    branches: [master, main]
+
+jobs:
+  lint-and-test:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - uses: actions/setup-python@v5
+        with:
+          python-version: "3.11"
+          cache: pip
+          cache-dependency-path: requirements-dev.txt
+
+      - name: Install dependencies
+        run: pip install -r requirements-dev.txt
+
+      - name: Ruff
+        run: ruff check scripts dashboard tests tool-list
+
+      - name: Pytest
+        run: python -m pytest tests/ -q
+
+  compile-c:
+    runs-on: ubuntu-latest
+
+    steps:
+      - uses: actions/checkout@v4
+
+      - name: Install build tools
+        run: sudo apt-get update && sudo apt-get install -y gcc g++
+
+      - name: Compile C/C++ tool-list demos
+        run: |
+          set -euo pipefail
+          gcc -Wall -Wextra -o /tmp/fastsort \
+            tool-list/algorithms/fastsort/fastsort.c
+          gcc -Wall -Wextra -o /tmp/greedy \
+            tool-list/algorithms/greedy/greedy.c
+          gcc -Wall -Wextra -o /tmp/arrtoheap \
+            tool-list/algorithms/heapsort/arrtoheap.c
+          gcc -Wall -Wextra -o /tmp/heapmax \
+            tool-list/algorithms/heapsort/heapmax.c
+          gcc -Wall -Wextra -o /tmp/inittree \
+            tool-list/algorithms/heapsort/inittree.c
+          gcc -Wall -Wextra -o /tmp/nil \
+            tool-list/algorithms/datastruct/nil_linklist.c
+          g++ -std=c++11 -Wall -Wextra -o /tmp/strSplit \
+            tool-list/algorithms/cpp/string/strSplit.cpp
+
+      - name: Smoke-run compiled binaries
+        run: |
+          /tmp/fastsort | tail -1
+          /tmp/greedy | head -1
+          /tmp/arrtoheap | head -1
+          /tmp/nil
+          /tmp/strSplit | tail -1

.gitignore

@@ -1,5 +1,6 @@
 # Python
 __pycache__/
+.pytest_cache/
 *.py[cod]
 *.pyo
 .Python
@@ -68,3 +69,12 @@ dashboard/data.json
 *.out
 *.exe
 *.dSYM/
+
+# Compiled C/C++ demos under tool-list (regenerate with gcc/g++)
+tool-list/algorithms/cpp/string/strSplit
+tool-list/algorithms/datastruct/nil
+tool-list/algorithms/fastsort/fastsort
+tool-list/algorithms/greedy/greedy
+tool-list/algorithms/heapsort/heapmax
+tool-list/algorithms/heapsort/arrtoheap
+tool-list/algorithms/heapsort/inittree

README.md

@@ -43,4 +43,16 @@ python3 scripts/build_dashboard_stats.py
 
 ## 依赖
 
-Python 3.10+，`pip install -r requirements.txt`
+Python 3.10+：
+
+```bash
+pip install -r requirements.txt          # 运行脚本与 SMO
+pip install -r requirements-dev.txt      # 开发：pytest、ruff
+```
+
+本地检查（与 CI 一致）：
+
+```bash
+ruff check scripts dashboard tests tool-list
+python3 -m pytest tests/ -q
+```

dashboard/server.py

@@ -6,10 +6,11 @@
 import json
 import subprocess
 import sys
+import threading
 from http.server import BaseHTTPRequestHandler, ThreadingHTTPServer
 from pathlib import Path
 from typing import Any
-from urllib.parse import urlparse
+from urllib.parse import unquote, urlparse
 
 ROOT = Path(__file__).resolve().parents[1]
 SCRIPTS = ROOT / "scripts"
@@ -26,6 +27,13 @@
 SOLVED_PATH = CATALOG_DIR / "solved-list.yaml"
 PORT = 8765
 
+# Allowed status values per catalog (see catalog/schema.md).
+READING_STATUSES = {"inbox", "active", "done", "archived"}
+PROBLEM_STATUSES = {"open", "wip", "blocked", "deferred", "solved"}
+
+# Serialize read-modify-write on YAML files (ThreadingHTTPServer is multi-threaded).
+_write_lock = threading.Lock()
+
 
 def refresh_data() -> None:
     subprocess.run(
@@ -35,14 +43,23 @@ def refresh_data() -> None:
     )
 
 
+def extract_id(path: str, prefix: str, suffix: str) -> str | None:
+    """Pull the URL-decoded id out of /<prefix>/<id>/<suffix> style paths."""
+    if not (path.startswith(prefix) and path.endswith(suffix)):
+        return None
+    middle = path[len(prefix) : -len(suffix)].strip("/")
+    return unquote(middle) or None
+
+
 def update_item_status(catalog: Path, item_id: str, status: str) -> bool:
-    items = load_yaml(catalog)
-    for item in items:
-        if item.get("id") == item_id:
-            item["status"] = status
-            item["updated_at"] = today()
-            save_yaml(catalog, items)
-            return True
+    with _write_lock:
+        items = load_yaml(catalog)
+        for item in items:
+            if item.get("id") == item_id:
+                item["status"] = status
+                item["updated_at"] = today()
+                save_yaml(catalog, items)
+                return True
     return False
 
 
@@ -80,21 +97,15 @@ def do_GET(self) -> None:
             if not DATA_JSON.is_file():
                 refresh_data()
             return self._send_json(200, json.loads(DATA_JSON.read_text(encoding="utf-8")))
-        if path.startswith("/api/reading/") and path.endswith("/detail"):
-            item_id = path.split("/")[3]
-            for item in load_yaml(READING_PATH):
-                if item.get("id") == item_id:
-                    return self._send_json(200, item)
-            return self._send_json(404, {"error": "not found"})
-        if path.startswith("/api/solved/") and path.endswith("/detail"):
-            item_id = path.split("/")[3]
-            for item in load_yaml(SOLVED_PATH):
-                if item.get("id") == item_id:
-                    return self._send_json(200, item)
-            return self._send_json(404, {"error": "not found"})
-        if path.startswith("/api/problem/") and path.endswith("/detail"):
-            item_id = path.split("/")[3]
-            for item in load_yaml(PROBLEM_PATH):
+        for prefix, catalog in (
+            ("/api/reading/", READING_PATH),
+            ("/api/solved/", SOLVED_PATH),
+            ("/api/problem/", PROBLEM_PATH),
+        ):
+            item_id = extract_id(path, prefix, "/detail")
+            if item_id is None:
+                continue
+            for item in load_yaml(catalog):
                 if item.get("id") == item_id:
                     return self._send_json(200, item)
             return self._send_json(404, {"error": "not found"})
@@ -113,16 +124,18 @@ def do_PATCH(self) -> None:
         if not status:
             return self._send_json(400, {"error": "status required"})
 
-        if path.startswith("/api/reading/") and path.endswith("/status"):
-            item_id = path.split("/")[3]
-            if update_item_status(READING_PATH, item_id, status):
-                refresh_data()
-                return self._send_json(200, {"ok": True, "id": item_id, "status": status})
-            return self._send_json(404, {"error": "not found"})
-
-        if path.startswith("/api/problem/") and path.endswith("/status"):
-            item_id = path.split("/")[3]
-            if update_item_status(PROBLEM_PATH, item_id, status):
+        for prefix, catalog, allowed in (
+            ("/api/reading/", READING_PATH, READING_STATUSES),
+            ("/api/problem/", PROBLEM_PATH, PROBLEM_STATUSES),
+        ):
+            item_id = extract_id(path, prefix, "/status")
+            if item_id is None:
+                continue
+            if status not in allowed:
+                return self._send_json(
+                    400, {"error": f"invalid status; allowed: {sorted(allowed)}"}
+                )
+            if update_item_status(catalog, item_id, status):
                 refresh_data()
                 return self._send_json(200, {"ok": True, "id": item_id, "status": status})
             return self._send_json(404, {"error": "not found"})

docs/TODO.md

@@ -13,8 +13,8 @@
 
 设计见 [UI-DESIGN.md](UI-DESIGN.md)（**v0.2 已确认**）。
 
-- [ ] P0：`scripts/build_dashboard_stats.py`（指标 + `dashboard/stats.json`）
-- [ ] P1/v1：`dashboard/server.py` + 前端
+- [x] P0：`scripts/build_dashboard_stats.py`（指标 + `dashboard/data.json`）
+- [x] P1/v1：`dashboard/server.py` + 前端
   - 默认 **阅读看板**；`archived` **默认折叠**
   - Tab：阅读 / 问题 / **题解**；顶栏 **`solved_count`**
   - **拖拽**改 reading/problem `status` 并写回 YAML
@@ -36,3 +36,5 @@
 - [x] Chrome 书签 / 历史 / 会话只读导入
 - [x] reading 指标（classify）与 reading → problem 转化
 - [x] 四清单框架与开源文档（SVG 流程图）
+- [x] Dashboard 指标聚合（`build_dashboard_stats.py` → `dashboard/data.json`）
+- [x] Dashboard 服务与前端（看板、题解 Tab、拖拽改状态写回 YAML）

requirements-dev.txt

@@ -0,0 +1,3 @@
+-r requirements.txt
+pytest>=8.0
+ruff>=0.8

requirements.txt

@@ -1 +1,4 @@
 pyyaml>=6.0
+numpy>=1.24
+# 可选：tool-list/.../unionFind.py 的渗流可视化、部分 legacy 脚本
+# matplotlib>=3.7

ruff.toml

@@ -0,0 +1,30 @@
+# Ruff config for maintained Python code (scripts, dashboard, tests, tool-list).
+# legacy/ is excluded — archived solutions, not lint-gated.
+
+target-version = "py310"
+line-length = 100
+
+exclude = [
+    "legacy",
+    ".pytest_cache",
+    "problem-list",
+    "reading-list",
+    "catalog",
+    "solved-list",
+    "dashboard/data.json",
+]
+
+[lint]
+select = [
+    "E",   # pycodestyle errors
+    "F",   # pyflakes
+    "I",   # isort
+    "W",   # pycodestyle warnings
+]
+ignore = [
+    "E501",  # line length — many legacy-style one-liners in tool-list
+]
+
+# Algorithm teaching code often uses l/r bounds and compact if-bodies.
+[lint.per-file-ignores]
+"tool-list/algorithms/**" = ["E701", "E741"]

scripts/_catalog_utils.py

@@ -69,18 +69,29 @@ def merge_by_key(
             continue
         if item_id in merged:
             base = merged[item_id]
+            changed = False
             for k, v in item.items():
                 if v in (None, "", [], {}):
                     continue
+                if k == "updated_at":
+                    continue
                 if k == "tags" and isinstance(v, list):
-                    base["tags"] = sorted(set(base.get("tags", []) + v))
+                    new_tags = sorted(set(base.get("tags", []) + v))
+                    if new_tags != base.get("tags"):
+                        base["tags"] = new_tags
+                        changed = True
                 elif k == "related" and isinstance(v, dict):
                     rel = base.setdefault("related", {})
                     for rk, rv in v.items():
-                        rel[rk] = sorted(set(rel.get(rk, []) + (rv or [])))
-                else:
+                        merged_rel = sorted(set(rel.get(rk, []) + (rv or [])))
+                        if merged_rel != rel.get(rk):
+                            rel[rk] = merged_rel
+                            changed = True
+                elif base.get(k) != v:
                     base[k] = v
-            base["updated_at"] = today()
+                    changed = True
+            if changed:
+                base["updated_at"] = today()
         else:
             item.setdefault("created_at", today())
             item["updated_at"] = today()